Re-exports are not documented.

[cameron-martin]

I am wanting to document an NPM package that is made up from multiple files, but re-exports the public interface at a top-level index.ts file, e.g:

index.ts

export { Foo } from './foo';
export { Bar } from './bar';

foo.ts

export class Foo {}
export class Baz {}

bar.ts

export class Bar {}

In this example, Baz is exported from foo.ts so that it can be used in other parts of the library, but is not part of the public interface of the library.

I am using typedoc to output json, then passing that to a custom renderer. However, the json contains no documentation entries for index.ts, instead only including documentation entries under the files where the class/function was originally exported.

However, I want to only render documentation for the things that are exported from the top-level index.ts file, and there seems to be no way to determine this from what typedoc outputs. Is there a workaround for this?

[aciccarello]

Hello @cameron-martin, Take a look at #259 which talks about some issues with re-exporting.

I also would love to see the ability to document only a public API (like is described in #639). This would help handle libraries much better.

[lddubeau]

I use façades that make heavy usage of export { .... } from "..." all over the place so this issue has become irritating enough for me to take a stab at solving it. The problem here is closely related to the one in #259 so I'm tackling both issues at the same time. The following case is easy enough to tackle:

const foo = 1;
export { foo }

because it is functionally the same as

export const foo = 1;

However both export { foo as somethingElse } and export { foo } from "./other-module" present issues that go beyond just generating declarations. One problem is that typedoc currently does not clearly distinguish symbols that are exported from a module from those that aren't. The flag --excludeNotExported is only fit only for some usages of typedoc. If I'm interested in producing documentation for consumers of a library, then I can use --excludeNotExported and everything is fine because I only want to show what is exported. But if I'm interested in producing documentation that covers everything I've ever documented for my project, then there's no distinction in the produced documentation between what is exported and what is not exported. Users have to go outside the documentation to figure it out.

Then there are the complications that export declarations introduce. (Terminological note: export { something } is an "export declaration" in TypeScript parlance.) Without export declarations, a symbol can either be available only internally, or available internally and externally under the same name (export default introduces a minor wrinkle in this but we can ignore it for now). With export declarations, a symbol can be:

1. Available only internally.

2. Available internally and externally, under the same name.

3. Available internally and externally, but the external name is different from the internal one. (Note that the external name is only valid externally: export { foo as bar } does not make bar available internally.)

4. Available only externally. (The export declaration export { foo } from "./someModule" does not make foo available internally.)

5. Available only externally and renamed. eg. `export { foo as bar } from "./someModule".

Cases 1 and 2 are currently handled ambiguously. Producing output for cases 3, 4, 5 right now would result in ambiguities worse than 1 and 2.

typedoc should systematically indicate in the generated documentation which symbols are available internally and which are available externally, this would resolve the ambiguity of cases 1 and 2 and would help tremendously with the other cases. Here's what I think should happen in each of the cases above:

1. Available only internally.

• no change from 0.11.0

2. Available internally and externally, under the same name.

• no flag: put an [exported] label in the output.

• --excludeNotExported: same as when using no flag, but omit [exported].

3. Available internally and externally, but the external name is different from the internal one. (Note that the external name is only valid externally: export { foo as bar } does not make bar available internally.)

• no flag: create a new declaration for bar that has the [exported] label and make that declaration refer to foo.

• --excludeNotExported: create a new declaration for bar which is the same as foo, except for the name.

4. Available only externally.

• no flag: create a new declaration for foo that has the [exported] label and make that declaration refer to foo in "./someModule".

• --excludeNotExported: same as when using no flag, but omit [exported].

5. Available only externally and renamed. eg. `export { foo as bar } from "./someModule".

• no flag: create a new declaration for bar that has the [exported] label and make that declaration refer to foo in "./someModule".

• --excludeNotExported: same as when using no flag, but omit [exported].

In the description above, I've set things up so that [exported] is omitted whenever --excludeNotExported is used. I'm on the fence about this. One the one hand, --excludeNotExported makes it redundant to mark symbols as exported or not, because everything in the documentation is necessarily exported. On the other hand, it is not immediately clear to readers that this is the case. They'd have to go outside the documentation to discover this fact: ask the developers, look at the build code that invokes typedoc, etc. Maybe part of the produced output could be changed to indicate that only exported symbols are visible. Like "Index of Exported Symbols" instead of "Index".

[cameron-martin]

It looks like Microsoft's API Extractor can help with this - particularly if you want to do the rendering yourself.

[Gerrit0]

Closing in favor of #596 / #639.