Typedoc: How to merge exports and global typings into the same entry point

[HoferMarkus]

I have a library which provides

• util functions within exported classes
• globally accessible typings within a certain namespace spread over multiple decleration files

Documenting these two parts works fine when using two individual entry points:
Entry point for export classes:

export { DemoClass } from '../../issue/lib';

Entry point for global typings in namespace:

declare namespace DemoNamespace {}

...this is a trick I found in https://github.com/TypeStrong/TypeDoc/issues/1424#issuecomment-752322225

This results in two modules, one for each entry point.

Now I want to get rid of the extra Modules layer so that the reader of the documentation can see the content (DemoClass & DemoNamespace) immediatly.
So I tried to just merge the code of the entry points into one:

export { DemoClass } from '../../issue/lib';

declare namespace DemoNamespace {}

However in this case the typings are not documented anymore.

I already tried to put the namespace decleration into a declare global block and played around with triple slash reference but I couldn't make it work.

/// <reference types="../../issue/typings" />

export { DemoClass } from '../../issue/lib';

declare global {
  namespace DemoNamespace {}
}

Is there a way to merge the exports and global typings into one entry points?

I just updated to TypeDoc version 0.20.20.
It wasn't an issue pre 0.20 since the mode: file and includeDeclerations options were available.

[Gerrit0]

There is - but you'll need a plugin. TypeDoc proper doesn't have a way to do this.

You can do this by using typedoc-plugin-not-exported and annotating your globals with @notExported (or pass the --includeTag xyz and use @xyz)

[HoferMarkus]

Thanks for the hint @Gerrit0!
The plugin looks very promising but unfortunately there seem to be problems with namespace declarations.
I tried to add a very basic namespace but I received the following error message when trying to build the docs:

RangeError: Maximum call stack size exceeded
    at new ContainerReflection (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\models\reflections\container.js:6:1)
    at new DeclarationReflection (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\models\reflections\declaration.js:16:9)
    at Context.createDeclarationReflection (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\converter\context.js:112:28)
    at Object.convertNamespace (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\converter\symbols.js:105:32)
    at Object.convertSymbol (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\converter\symbols.js:71:79)
    at Converter.convertSymbol (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\converter\converter.js:52:19)
    at Converter.lookForFakeExports (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc-plugin-not-exported\dist\main.js:49:35)
    at triggerEvents (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\utils\events.js:183:43)
    at triggerApi (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\utils\events.js:149:13)
    at eventsApi (C:\Users\mahof\Documents\Repos\GlobalTypesExportIssue\node_modules\typedoc\dist\lib\utils\events.js:42:18)

The entry point file in my minimized test repository looks like this:

export { DemoClass } from './module'

/** @notExported */
declare namespace DemoNamespace {
    interface DemoITF {
        param: number;
    }
}

The DemoClass is exported from this file:

export class DemoClass {
    static DemoFunction(param: number) {}
}

I use the following package versions:

"typedoc": "0.20.23",
"typedoc-plugin-not-exported": "0.1.3",
"typescript": "3.9.0"

Is it fine to address this issue here or should I move it into the Issue section of the typedoc-plugin-not-exported GitHub repository?

[Gerrit0]

Normally I'd point you to that plugin - but this works since the bug is in code I provided.

@tomchen the fix for this crash is pretty easy, just need to ensure that the symbol is declared in this scope, not just visible in this scope:

    const symbols = context.checker
      .getSymbolsInScope(node, TypeScript.SymbolFlags.ModuleMember)
      .filter(
        (symbol) =>
          symbol.getDeclarations()?.some((d) => d.parent === node) &&
          !exportedSymbols.includes(symbol)
      )

[tomchen]

Yeah. typedoc-plugin-not-exported v0.1.5 v0.1.4

[HoferMarkus]

Thanks for that fast fix, but I fear I have to bother you one more time.

Eventhough the documentation can be created for the demo example described above, it won't cover the declarations from different files under the same namespace.

I added the following code in a new file:

declare namespace DemoNamespace {
    interface DemoITF2 {
        param: number;
    }
}

So I would expect, that DemoITF and DemoITF2 get exposed in the documentation of namespace DemoNamespace as described in https://github.com/TypeStrong/typedoc/issues/1424#issuecomment-752322225
Unfortunately only DemoITF is available, whereas it used to work when I used 2 different entry points as described in the original question.

We have multiple declaration files within the same parent namespace for better repository structure so we can avoid having to declare all exposed typings in just one file.

[Gerrit0]

I suspect this might be another similar issue as the one here https://github.com/TypeStrong/typedoc/issues/1474#issuecomment-775159176... though likely easier to solve. I'll need to take a closer look later this week (most likely Saturday...) but I think this can be resolved by getting the parent's symbol and checking for any of its declarations instead of just the first declaration.

[HoferMarkus]

Thanks, that would be awesome!

[Gerrit0]

Well, it's kind of ugly... but so long as the namespace is wrapped with declare global somewhere so that TypeDoc can detect the symbol is global the next version of typedoc-plugin-not-exported should handle it.

[tomchen]

OK. typedoc-plugin-not-exported v0.1.6

[krisztianb]

If you want to get rid of the extra modules layer, you might also want to try this plugin: https://github.com/krisztianb/typedoc-plugin-merge-modules

Its only goal is exactly that: to get rid of the extra modules layer.

[Gerrit0]

Oh neat! I didn't realize you'd gotten around to publishing that, that's probably the better answer here.

[HoferMarkus]

I tried the new typedoc-plugin-not-exported version as well as typedoc-plugin-merge-modules => both solutions work for me 👍
So thanks for the great support here, for me the issue can be closed.