Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inconsistent treatment of variable signatures containing constructors #2036

Closed
ejuda opened this issue Aug 17, 2022 · 1 comment
Closed

Inconsistent treatment of variable signatures containing constructors #2036

ejuda opened this issue Aug 17, 2022 · 1 comment
Labels
bug Functionality does not match expectation

Comments

@ejuda
Copy link
Contributor

ejuda commented Aug 17, 2022

Search terms

variable, signature, constructor, type literal

Expected Behavior

Consider the following code:

// index.d.ts

declare const SingleSimpleCtor: {
    new (a: string, b: string): Array<string>;
}

declare const MultipleSimpleCtors: {
    new (a: string, b: string): Array<string>;
    new (a: string, b: number): Array<string|number>;
}

I would expect TypeDoc to document the constructor signatures contained in the variable declaration.

Actual Behavior

TypeDoc does not document these constructor signatures:

image

image

I believe this is because typeLiteralConverter does not check for constructor signatures (shown in the AST - see it here - as ConstructSignature nodes).

Oddly enough, sometimes the constructors are documented correctly. Consider the following code:

// index.d.ts

declare class SingleAdvancedCtorImp<T> {
    constructor(value: T, ...keys: PropertyKey[]);
}

interface SingleAdvancedCtor<T> extends SingleAdvancedCtorImp<T> {
}

declare const SingleAdvancedCtor: {
    new <T, P extends keyof T>(value: T, ...keys: P[]): SingleAdvancedCtor<T>;
};

for which TypeDoc renders the following:

image

This is likely because the symbol associated with the variable declaration is also associated with the interface declaration (see the associated AST here). When TypeDoc extracts the declaration from the symbol in convertVariable function, it happens to get the interface declaration, which is why the ts.isVariableDeclaration check fails and we eventually end up using constructorConverter.

As soon as we add a second constructure signature:

// index.d.ts

declare class MultipleAdvancedCtorsImp<T> {
    constructor(value: T, ...keys: PropertyKey[]);
}

interface MultipleAdvancedCtors<T> extends MultipleAdvancedCtorsImp<T> {
}

declare const MultipleAdvancedCtors: {
    new <T, P extends keyof T>(value: T, ...keys: P[]): MultipleAdvancedCtors<T>;
    new <T>(value: T): MultipleAdvancedCtors<T>;
};

we revert back to the typeLiteralConverter and the constructor signatures are not rendered:

image

Steps to reproduce the bug

  1. Clone the reproduction repository.
  2. npm ci
  3. npm run docs
  4. This will generate documentation into docs directory.

Environment

  • Typedoc version: 0.23.10
  • TypeScript version: 4.7.4
  • Node.js version: 16.15.0
  • OS: Windows 10
@ejuda ejuda added the bug Functionality does not match expectation label Aug 17, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Aug 26, 2022

Very complete bug report, thanks! I think your analysis is correct.

@Gerrit0 Gerrit0 closed this as completed in 02ec72b Sep 1, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation
Projects
None yet
Development

No branches or pull requests

2 participants