typedoc-plugin-internal-external
Version:
Force a File or Reflection (symbol) to be @internal or @external
119 lines (81 loc) • 2.63 kB
Markdown
## typedoc-plugin-internal-external
### What
A plugin for [Typedoc](http://typedoc.org)
Use an annotation (in a comment) to set code to "Internal" or "External".
### Examples
```
/** make this function @internal */
function internalFunction() {
}
```
```
/** make this class @external */
class ExternalClass {
}
```
```
/** @external Make all the code in this file (Dynamic Module) external */
/** A function in the dynamic module */
function func1() {
}
/** Another function in the dynamic module */
function func2() {
}
```
# Why
Typedoc categorizes your code into "Internal" and "External".
Essentially:
- Internal: Your own code
- External: Everything else
When using the default theme, typedoc provides a checkbox to show/hide the generated "External" documentation.
Typedoc uses the `files: []` array (in `tsconfig.json`) to determine if code is "Internal".
If a file being parsed is in the `files: []` array, then the code in that file is "Internal".
These annotations allow you to force code to be internal or external.
### Installing
Typedoc 0.4 has the ability to discover and load typedoc plugins found in node_modules.
Simply install the plugin and run typedoc.
```
npm install --save typedoc-plugin-internal-external
typedoc
```
### Using
Add `` or `` to a comment.
That code's typedoc `Reflection` will have the `isExternal` boolean set accordingly.
```js
/**
* @internal
* This should always appear in the generated documentation
*/
class MyInternalClass {
}
/**
* @external
* This should only appear in the generated documentation when "Externals" is checked
*/
class MyExternalClass {
}
```
#### Annotation Aliases
Although the original purpose behind `Externals` was to hide documentation generated for external code,
you can use the show/hide feature of the default theme to hide whatever code you choose, by marking it as ``.
For example, you may have an internal API that you don't want shown in your docs by default.
Because marking "internal API" with "External" is counter-intuitive, you can choose an alias for the `` annotation.
On the typedoc command line, define the aliases:
```
typedoc ....... --internal-aliases internal,publicapi --external-aliases external,internalapi
```
Then you can use those aliases in your comments:
```
/**
* This should always appear in the generated documentation
*/
class PublicClass {
}
/**
* @internalapi
* This internal api's `Refletion` has `isExternal === true`, and should
* only appear in the generated documentation when "Externals" is checked
*/
class InternalClass {
}
```