@template tag documentation not validated for classes

[shannon]

Search terms

@template validation constructor

Expected Behavior

Typedoc validation should not warn about lack of documentation on TypeParameter defined at the class level.

Actual Behavior

Typedoc warns that the TypeParameter is not documented when it is in fact documented using a @template tag.

typedoc
[warning] Test.constructor.T (TypeParameter), defined in <unknown>/<path>/test-template.js, does not have any documentation
[warning] Found 0 errors and 1 warnings

The actual resulting documentation includes the description so I believe it understands the syntax, it's just the validation warning that is not correct. For completeness I tried the @typeParam tag instead and it does not result in the warning but this tag is not recognized by other tools that I am using so it's not an option really.

Steps to reproduce the bug

Run typedoc against the following file:

//test-template.js
/**
 * Test for Type Parameters on Constructor Signatures being ignored.
 *
 * @template T - This is documentation for T
 */
export class Test {

}

With the following config:

//typedoc.config.js
const config = {
    name: "Documentation",
    entryPoints: ["./test-template.js"],
    out: "doc",
    compilerOptions: {
        checkJs: true,
        target: 'esnext',
        module: 'esnext',
        moduleResolution: 'node',
    },
    skipErrorChecking: true,
    validation: {
        notDocumented: true,
    },
    requiredToBeDocumented: [
        "Constructor",
        "TypeParameter"
    ]
};

export default config;

Environment

• TypeDoc version: 0.28.14
• TypeScript version: 5.8.3
• Node.js version: v22.15.0
• OS: Both Windows and Ubuntu

Edit: It actually doesn't even need the constructor to be included, so I simplified the reproducer.

[Gerrit0]

Thank you for the reproduction! This is coming from the type parameter on the constructor not inheriting the type parameter documentation from the class. The following will silence the warning:

//test-template.js
/**
 * @template T - class level type param T
 **/
export class Test {
  /** @template T - docs for ctor T */
  constructor() {}
}

It seems reasonable to me for TypeDoc to copy the @template from the class to the constructor so that if not otherwise documented it will inherit the docs

[shannon]

Ah ok, thanks @Gerrit0 for taking the time to respond.

The problem I having with that workaround is that Deno does not like this extra type parameter declaration

I'm inclined to think that Deno is more correct here since you wouldn't write it this way in ts:

export class Test<T> {
  constructor<T>() {}
}

So the intention of adding a @template tag on the constructor becomes ambiguous (i.o.w. the @template tag adds the type parameter to the signature in js as opposed to just documenting it).

In both Deno and tsc this results in an error 1092.

I did some more testing and it looks like the issues is not strictly caused by the @template tag. The same issue occurs using the @typeParam tag in a ts file. But not in a js file which is why I missed it.

//test-template-ts.ts
/**
 * @typeParam T - class level type param T
 **/
export class Test<T> {

}

//test-template-js.js
/**
 * @typeParam T - class level type param T
 **/
export class Test {

}

typedoc
[warning] test-template-ts.Test.constructor.T (TypeParameter), defined in <unknown><path-redacted>/typedoc-test/test-template-ts.ts, does not have any documentation
[info] html generated at ./doc
[warning] Found 0 errors and 1 warnings

The results are different for each though.

So it seems there is a bit of inconsistency here.

If you do follow the workaround(using either @template or @typeParam it results in duplicate Type Parameters defined the result. I presume the same would occur if the solution was to copy the docs to the constructor.

This seems undesirable so in my opinion it would be better to adjust the validate to ignore any associated typeParameters when validating a constructor. It should already be validated by the Class kind anyways and this seems more inline with the intended coding conventions from a typescript perspective.

[shannon]

Sorry just a quick follow up. I just realized, it creates a separate type parameters section for the constructor regardless of what you do. So I honestly don't know if that's desirable. I wasn't expecting it, but if that's how it normally works then copying the documentation makes more sense.