Merge documentation for nested types

[slavafomin]

Search Terms

merge types / merge declarations / merge properties / merge documentation

Problem

Hello!

I've created a repository to demonstrate my problem. Please, take a look at this source file:

export interface ParamsBag <ParamsType> {
  params: ParamsType;
  qux: boolean;
}

export interface MyFuncParams {
  foo: string;
  bar: number;
}

export type MyFuncOptions = ParamsBag<MyFuncParams>;

export function myFunc(options: MyFuncOptions): void {
}

It defines a simple function myFunc that has a single argument of type MyFuncOptions, which builds upon two other types: ParamsBag and MyFuncParams. So there are three types involved when it comes to the function argument, but the final merged type declaration is quite simple:

export interface MyFuncOptions {
  params: {
    foo: string;
    bar: number;
  };
  qux: boolean;
}

However, typedoc will generate 3-4 pages for this function and it's argument where each type is declared separately. This is quite precise, but from the end-user perspective who will read the documentation this is absolutely unreadable. The user will have to build the merged type declaration in it's head to understand the structure of the function's argument.

Suggested Solution

Instead, it would be much better to merge all this type information to generate a single page that will describe the function argument. Ideally, it should look somewhat like this.

Is it possible to do? Would this be hard to implement? The thing is that it is pretty common in TypeScript projects to have resulting type built from dozen of other generics and type-helpers. Currently the documentation generated for such types are practically useless and I can't use typedoc to document my libraries.

Thank you!

[Gerrit0]

Similar to #1519, #2032. I suspect this will be something that someday ends up as a plugin, but I'm not sure it will ever be a part of TypeDoc itself.

[Gerrit0]

It's worth mentioning, however, that in this case you can do:

export interface MyFuncOptions extends ParamsBag<MyFuncParams> {}

Which, because it's an interface, means that TypeDoc will resolve all of the type members to give you:

[slavafomin]

It's worth mentioning, however, that in this case you can do:

That's good to know, thanks. I will try to use this approach where applicable as a workaround.

but I'm not sure it will ever be a part of TypeDoc itself

Please allow me to disagree. Using "reflective" typing, type aliases and type helpers is so common in TypeScript, that I believe that it's not only must be a core feature, but it is actually a critical feature. In my case, I don't see any use for documentation generated by TypeDoc, because it's impractical to use by the end users. I have had to change the structure of my library and have spend couple of days refactoring it just to allow TypeDoc to generate somewhat useful docs.

[Gerrit0]

There's nothing to disagree with - it's more a statement of that I'm unlikely to ever get around to implementing it. I've been more and more busy with non-typedoc projects.

[Gerrit0]

Closing in favor of #1519

[Dayday10]

Thanks Garrett