@princjef/api-documenter


Automatic documentation of public APIs for Typescript packages.

This package is forked from [@microsoft/api-documenter][api documenter] and is
meant to be used alongside [@microsoft/api-extractor][api extractor]. It has
been updated with the following adjustments/capabilities:

- Nested folder structure to more easily understand API structure and support
[declaration merging][]
- Includes class and interface hierarchies with links to parent/child classes
and interfaces
- Inlines class/interface members with deep linking to reduce amount of
navigation needed
- Overrides automatically inherit documentation of superclass/interface members
that are documented
- Inlines inherited members for classes and interfaces to make the full contract
viewable in one place
- Fixes up the navigation breadcrumb to make the package entry point the
homepage, rather than asusming that there will be multiple packages present

Usage

To use this package, you will typically want to install it alongside the [API
Extractor][] tool:

``
npm install --save-dev @microsoft/api-extractor @princjef/api-documenter
`

To get API Extractor to work with the documenter, you will need an
api-extractor.json file like the following in your repository:

`json
{
"compiler": {
"configType": "tsconfig",
"rootFolder": "."
},
"project": {
"entryPointSourceFile": ""
},
"apiJsonFile": {
"enabled": true,
"outputFolder": "./temp"
}
}
`

With the configuration above, you can then generate your documentation by
running:

`
api-extractor run && api-documenter --input ./temp --output

`

Running this will output markdown files for your API to the folder specified.
You can either use these output files directly or integrate it with a
documentation site of your choosing.

Frequenetly Asked Questions

What documentation tags can I use?

This package relies on a slightly modified version of JSDoc comments called
[AEDoc][]. Work is ongoing to standardize this into a [TSDoc][] specification.

Why am I seeing an error about a missing release tag?

[API Extractor][] requires all exported items (classes, interfaces, types,
namespaces, etc.), to be labeled with one of the four visibility filters
(@public, @beta, @alpha, @internal) to make the usage explicit. If you
want to get rid of the warning and include the item as a regular exported
member, add the @public` tag on its own line at the end of the doc comment for
the item.

Contributing

See [CONTRIBUTING.md][contributing] for full contribution guidelines.

[aedoc]: https://api-extractor.com/pages/tsdoc/syntax/
[tsdoc]: https://github.com/Microsoft/tsdoc
[api extractor]: https://api-extractor.com/
[api documenter]:
https://github.com/Microsoft/web-build-tools/tree/master/apps/api-documenter
[declaration merging]:
https://www.typescriptlang.org/docs/handbook/declaration-merging.html
[contributing]: ./CONTRIBUTING.md