Specify the Typedoc Module of a file using @module annotation
npm install typedoc-plugin-external-module-nameA Typedoc plugin which allows code documentation to be organized into custom Modules.
_Note: In Typedoc 0.17.0 and above, Module refers to an ES6 Module._
_In Typedoc 0.16.x and below, an ES6 Module was called an External Module._
_Although the plugin's name includes "External Module", it modifies Modules (ES6 Modules)_
By default, Typedoc creates a Module for each ES6 Module (each file).
This plugin allows documentation to be moved to arbitrary modules.
It also supports merging multiple modules into a single module.
By default, all Modules in a given directory will be merged into a single module.
Suppose your source files are organized like this:
```
thing1/foo.ts
thing1/bar.ts
thing2/baz.ts
thing2/qux.ts
By default, Typedoc would create four Modules:
- thing1/foo: contains foo documentationthing1/bar
- : contains bar documentationthing2/baz
- : contains baz documentationthing2/qux
- : contains qux documentation
With this plugin, Typedoc creates two Modules:
- thing1: contains foo and bar documentationthing2
- : contains baz and qux documentation
Typedoc has the ability to discover and load typedoc plugins found in node_modules.
Simply install the package usng your package manager and run typedoc.
``
npm install -D typedoc-plugin-external-module-name
typedoc
This plugin will combine documentation from the files in each given directory into a new Module.
The new module name is generated from the directory's location in the source tree.
You can explicitly specify a Module name using the @module annotation.@module modulename
Add a comment block at the top of a Typescript file with .@packageDocumentation
Mark the comment block as to let typedoc know that this is documentation for the file (Module) itself
(see: Typedoc Docs).
`js`
/**
* @packageDocumentation
* @module module1
*/
When multiple modules are merged, the merged module summary is chosen arbitrarily from the first file processed.
To use a specific file's comment block as the Module page summary, use @preferred.
`js
/**
* This comment will be used as the summary for the "thing2" module.
* @packageDocumentation
* @module thing2
* @preferred
*/
`
Create a file named .typedoc-plugin-external-module-name.js in the folder you launch typedoc from.
Create a custom mapping function in that file and export it using CommonJS.
For each Module, the plugin will call your function and use the return value as the Module Name.
``
module.exports = function customMappingFunction() {
return "custom" // everything goes into "custom"
}
The Function should have the following signature:
`
type CustomModuleNameMappingFn = (
explicitModuleAnnotation: string,
implicitFromDirectory: string,
path: string,
reflection: Reflection,
context: Context,
) => string;
`
The arguments are:
- moduleAnnotation: If the module has an explicit annotation, i.e., @module explicitimplicitFromDirectory
- : The plugin's default mappingpath
- : The path to the filereflection
- : The Module ContainerReflectioncontext
- : The typedoc Context
Example:
`${package}/${implicit}
const subpackage = new RegExp("packages/([^/]+)/");
module.exports = function customMappingFunction(explicit, implicit, path, reflection, context) {
// extract the monorepo package from the path
const package = subpackage.match(path)[1];
// build the module name
return ;``
}