Module names not fully working (partially ignored)
AlCalzone opened this issue · comments
I have a problem that I am unable to solve by looking at the documentation alone.
In my project https://github.com/AlCalzone/shared-utils/tree/master/src I have a bunch of folders, each of which should be treated like a module and can be imported separately (e.g. require("alcalzone-shared/math")). Each folder has an index.ts which exposes the functionality of that "module". These index.ts files are annotated with /** @module module-name */.
I'm generating the documentation with typedoc and this module. That partially works:
As you can see, helpers, math, strings and typeguards have the correct module name format. The other modules don't - collections/index has the annotation /** @module collections */.
And there are links to the internal implementation files of the modules (e.g. collections/expiring-set) that don't even have an @module annotation and are still included in the table of contents.
Am I doing something wrong or is this a bug?
Try again with release 4.0.0. It will (by default) merge all files in a directory into a single typedoc Module based on the directory name.
Looks different, but still not working. The modules that were wrong above are now hidden behind a single link:
two directories deep into Module:
oh interesting. I'll pull your repo down and try to see what is going on
Try with 4.0.2. I changed how the automatic module names are guessed. I also suspect there may be some problem related to windows paths. It works ok on Mac though with your repo and 4.0.2.
If this works, I'd suggest removing all the manually added "@module" entries from your source code.
Also your original problem is probably because the module comments do not have @packageDocumentation annotations.
/** @packageDocumentation @module modulename */
This was introduced in typedoc 0.16 I think. Otherwise you need a dummy comment block right after the module comment block.
Old way:
/** @module modulename */ /** */
Ok so I upgraded to 4.0.2 and removed all @module comments. It looks better now, but all modules have a src\ prefix:
If I use
/** @packageDocumentation @module modulename */
it works correctly.
Admittedly, the automatic guessing is more convenient. Is there a way that the src path can be stripped out automatically?
Interesting it doesn’t add the src prefix on macOS. I don’t have windows to test unfortunately. You can try adding ”baseUrl”: “./src” to tsconfig.json.
If that doesn’t work you can add a custom mapping function to your repo. Check out the updated readme for details.
Released 4.0.3 which should hopefully fix autodetection for windows users (avoid the src\ prefix)
https://github.com/christopherthielen/typedoc-plugin-external-module-name/releases/tag/4.0.3
It works, thank you!