Using this module creates an empty comment block on the generated page

[AlCalzone]

File 1 (with @module comment):

File 2 (without @module comment):

[zgramana]

Reproduction

I've been able to figure out the root cause and a work around. It appears that the blank comment is rendered when two conditions are met:

1. The /** @module FOO */ is present.
2. The next non-whitespace token is a /** (a non-JSDoc comment begin token /* is not sufficient to reproduce this).

When the conditions are met, the @module FOO is removed from the existing JSDoc comment but the (by now empty) comment itself is left intact. This is then rendered as an empty comment block in the HTML output.

Workaround

This can be exploited to achieve a section header by doing two things:

1. Find the "merge target module" file. See discussion below.
2. Move the @module FOO statement to it's own line.
3. Placing the desired module landing page content in the comment before the line from the previous step. Putting it after will not work. It makes no difference whether it is a single line comment or has multiple.

The desired content can be markdown or an include, both work. Here is an example:

/**
 * # Welcome to My Module!
 * This is great stuff.
 * 
 * ```ts
 * let codeBlocks = 'work'; // as expected!
 * ```
 * [[include:fileFromIncludeFolder.md]]
 *
 * @module FOO
 */

/**
  * Here is my model class.
  */
export class MyFoo {
  name: string;
}

The following compact variant works as well:

/** [[include:fileFromIncludeFolder.md]] @module FOO */
/**
  * Here is my model class.
  */
export class MyFoo {
  name: string;
}

Everything from the first comment will end up on the module's landing page, and everything after will render as expected on the page for the MyFoo class.

The 'merge module'

This plugin looks for an existing module to rename to the desired name. It refers to this as the merge target. After processing is complete, it will then remove the @module tag from the comment. I'm guessing that it uses a great pattern match which matches on anything from @module until *\. As a result, anything in the comment before @module remains in tact.

As a result, to take advantage of the work around you have to either locate the file while the plugin will choose as the merge target, or you need to put the landing page content on every class file that you assign to a given module. I have not yet seen a pattern that allows one to predict which module will become the merge target, so I've initially used trial and error. So far both merge target modules were simple model classes, and lexicographic sort order of the file paths did not seem to influence the process.

[christopherthielen]

released https://github.com/christopherthielen/typedoc-plugin-external-module-name/releases/tag/2.2.1