Category description is missing in the generated documentation

[aayla-secura]

Hi there, thanks for the great plugin.

Is there any way to merge the module-level comments when using mergeModulesMergeMode: "module"?

I have several files which I want merged as one module and each one provides a @categoryDescription for its relevant categories. In the output I can only see the category description of the first file that's in that module.

I've tried using:

---

Method 1:

catA.js:

/**
 * @module SomeModule
 *
 * @categoryDescription CategoryA
 * ...
 */

catB.js:

/**
 * @module SomeModule
 *
 * @categoryDescription CategoryB
 * ...
 */

---

Method 2:

catA.js:

/**
 * @module SomeModule
 */

/**
 * @packageDocumentation
 * @categoryDescription CategoryA
 * ...
 */

catB.js:

/**
 * @module SomeModule
 */

/**
 * @packageDocumentation
 * @categoryDescription CategoryB
 * ...
 */

---

I've also tried adding the @mergeTarget tag to each comment, right under @module but if I understand correctly this is meant to select only one module comment, rather than merging them all? But in case case I get an error "Encountered an unknown block tag @mergeTarget"...

Is there a way to have all category descriptions show on the module summary page while still having the descriptions in separate files?

[krisztianb]

Hi. I'm glad the plugin is helpful to you.

I haven't been aware of the tag @categoryDescription and there also is one called @groupDescription for groups. (But as a kind of excuse: I'm not using TypeDoc anymore for any projects.)

I'm not entirely sure that I understand what you are looking for. So we should clarify this first. What exactly is your desired output for the examples you posted above? You don't seem to have the same category in both modules, so I don't see what should be merged.

But it is true that if you look here in the code you can see that only the children of the categories are merged and nothing else (description).

[aayla-secura]

Hey, thanks for replying. My desired out is for the merged module summary page to include the description for all categories. Currently, with the examples above, only the description for categoryA would be included on the page, although categoryB is parsed, shown as a heading, etc, but it has no description.

The @categoryDescription must be in the module comment, it cannot be in one of the comments to the functions that are categorized. So it looks like the only way to achieve what I want is to have all the category descriptions in a single file that's the first one in alphabetical order?

[krisztianb]

Currently I would expect the plugin to collect all categories from all files that have the same module name. So for your example above there should be one module SomeModule with two categories CategoryA and CategoryB. The descriptions are taken from the first file the category appears in. So if the categories are only used in one file the descriptions should not be missing. If however for example catA.js also contains something categorized with CategoryB and is parsed before catB.js then that would explain why CategoryB has no description in the docs. Do you see what I mean?

However extending the plugin into reading the description from all files should not be a problem.

[aayla-secura]

Hmm, it doesn't seem to be the case. I just did a minimal working example:

catA.ts

/**
 * @module test
 *
 * @categoryDescription Category A
 * This is category A
 */

/**
 * @category Category A
 */
export const funcA = () => {};

catB.ts:

/**
 * @module test
 *
 * @categoryDescription Category B
 * This is category B
 */

/**
 * @category Category B
 */
export const funcB = () => {};

And the result is:

Only Category A has the description.

Here's my typedoc config:

    "typedocOptions": {
        "entryPoints": [
            "src/ts/"
        ],
        "entryPointStrategy": "expand",
        "out": "docs/",
        "plugin": ["typedoc-plugin-merge-modules"],
        "mergeModulesMergeMode": "module" // added by plugin typedoc-plugin-merge-modules
    },

[krisztianb]

That is unexpected. This would mean that Category B (for some reason) already exists in the module when the second module file is parsed. I will have to debug this to see what is really going on here.