typedoc

typedoc copied to clipboard

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.