Inheritance between "groups" and "categories" works different than I'd expect

[hybridherbst]

Search terms

categories, groups, options

Expected Behavior

I'm trying to structure code with both groups and categories. However, it's not clear to me what has precedence when and when each of those is ignored.

What I would like to achieve is a sorting where "Groups" come first - e.g. "Components" – and then, inside that, the categories.

To me it looks like it might be an issue with inheritance – it looks like when both category and group are specified, then I get the ordering that I expect; but when group is specified on a parent class, that is only inherited by classes that do not specify a category.

In other words: I would expect that in "Case E", "Category A" and "Category B" are nested under "Components", not under "Classes".

(Side note: the docs mention that "categorizeByGroup" is true by default, but it seems actually it's false by default)

Code:

export function add(a, b) {}

/**
 * @group Components
 */
export function sum(a, b) {}

/**
 * @group Components
 */
export class MyClass {}

export class MyClass2 extends MyClass {}

/**
 * @category CategoryA
 */
export class MyClass3 extends MyClass {}

/**
 * @category CategoryB
 */
export class MyClass4 extends MyClass {}

Results by config:

Case	Config	Result
A	"navigation": { "includeFolders": false, "includeCategories": false, "includeGroups": true }, "categorizeByGroup": false
B	"navigation": { "includeFolders": false, "includeCategories": true, "includeGroups": true }, "categorizeByGroup": false
C	"navigation": { "includeFolders": false, "includeCategories": true, "includeGroups": false }, "categorizeByGroup": false
D	"navigation": { "includeFolders": false, "includeCategories": false, "includeGroups": true }, "categorizeByGroup": true
E	"navigation": { "includeFolders": false, "includeCategories": true, "includeGroups": true }, "categorizeByGroup": true
F	"navigation": { "includeFolders": false, "includeCategories": true, "includeGroups": false }, "categorizeByGroup": true

Actual Behavior

This structure loses the group on MyClass3, MyClass2 properly has the group:

/**
 * @group Components
 */
export class MyClass {}

export class MyClass2 extends MyClass {}

/**
 * @category CategoryA
 */
export class MyClass3 extends MyClass {}

This structure properly nests MyClass in Component > Category, which is inherited by MyClass2, but then MyClass3 loses the group that it should inherit:

/**
 * @group Components
 * @category CategoryC
 */
export class MyClass {}

export class MyClass2 extends MyClass {}

/**
 * @category CategoryA
 */
export class MyClass3 extends MyClass {}

Steps to reproduce the bug

Full repro: https://stackblitz.com/edit/vitejs-vite-yz5hhi? Adjust settings in typedoc.json and src/index.ts as needed.

[Gerrit0]

This is working as designed.

Grouping/categorization is applied for a given reflection by looking for the @category and @group tags within that reflection's comments, but MyClass3 in your example has provided a custom comment, which means that it does not inherit the parent class's comment. As MyClass3 then does not include a @group tag, it is placed in the default group for it's kind - Class

Groups/categories could be given their own custom inheritance logic which works the way you describe, but I think that would be overall more confusing to most users as it introduces another possible way that comment inheritance is handled. The current rule of following regular comment inheritance is straightforward.

[hybridherbst]

Sorry, didn't see your response.

The current rule of following regular comment inheritance is straightforward.

What is the current rule? "Inherit if no comment, don't inherit if any comment"?

[Gerrit0]

The current rule is "follow regular comment inheritance"

Comments are inherited if a member does not specify a comment, or that member uses the @inheritDoc tag