Missing global namespace/side effect

[mistic100]

Sorry if the title is incorrect/misleading, I am not sure what part is involved or not

Context

I create a library for Cypress, if you don't know it exposes a global "cy" variable which contains methods to interact with the DOM. Methods can by added with Cypress.Commands.addQuery (thus it is a side effect), and the Typescript namespace is augmented to make the IDE aware of these new methods

Having a lot a custom methods to add, I splitted my library into multiple files (forms, widgets, datagrid, etc) imported by the entry point (just imports, no exports).

This is the entry point of the library, it only imports other files.

Expected Behavior

The generated documentation contains all my custom methods added to the Cypress namespace (as well a a custom namespace).

Actual Behavior

The documentation is empty.
If I use global.cmd as entry point, the documentation seems complete, but I cannot but everything in a single file.

Steps to reproduce the bug

Example repo : https://github.com/mistic100/typedoc-cypress use ci:documentation NPM script to generate the doc.

Environment

• Typedoc version: 0.24.8
• TypeScript version: 4.9.5
• Node.js version: 18

[Gerrit0]

Globals are a terribly messy thing. TypeDoc's support for them is very limited, and is effectively a best effort guess on what ought to be documented for a file.

1. If an entry point is a module, TypeDoc will document exports + re-exports, with some special handling for export=.
2. If an entry point is not a module, TypeDoc will document globals defined in that file.

Unfortunately, this means that your use case is neatly outside of what is supported by TypeDoc... At this point, until #2281 is done, I'd recommend using typedoc "src/**/*.cmd.ts" (quotes important to let TypeDoc do the expansion rather than your shell) and typedoc-plugin-merge-modules to merge all of the resulting modules into a single module. (I think that plugin will merge the duplicate Cypress namespaces, but am going off several month old memory here)

[mistic100]

That seems to produce a usable documentation.

The plugin however is no use in that case, it just strips the module object, the Cypress namespace is not merged but instead displayed multiple times.

I let you close this issue if you do not plan to make changes in typedoc handling.

Thanks

[Gerrit0]

TypeDoc will eventually do merging as well, but I'm tracking that under #2281