@fluentui/api-docs

Processes package-name.api.json files generated by API Extractor into ComponentName.page.json files used to populate API reference tables, mainly in the Fluent UI website's Controls section.

Using the tool

1. In each API item which should be included on the website (see Limitations below for supported item types), include a {@docCategory PageName} annotation in its top-level doc comment. If the item is related to a specific component, PageName should be the name of the component. Otherwise, you can use either the name of the item or a general category that it falls under.

``ts
/**
* Comment about the props
* {@docCategory Foo}
*/
interface FooProps {}
`

2. Add a config and build step to run API Extractor on your package. (Fluent UI has a shared config extended by each package's config.)

3. Somewhere in your repo (probably in the package that displays the documentation), add a build step to invoke the generatePageJsonFiles API. For the config object, see IPageJsonOptions in this file for docs and this file for an example.

`js
const { generatePageJsonFiles } = require('@fluentui/api-docs');
const config = {}; // your config here
generatePageJsonFiles(config);
`

4. To render the info from *.page.json files, you can either use ApiReferencesTableSet from @fluentui/react-docsite-components, or use its logic as a template for your own control.

Limitations

$3

Documenting the following API items/types is supported:

- Interfaces
- Type aliases
- Classes
- Enums

These API items/types are not supported currently (PRs welcome):

- Functions (including function components)
- Constants

$3

If you're using ApiReferencesTableSet for rendering the output, top-level doc comments have full markdown support, but individual prop comments have limited support (currently just inline code blocks) due to performance concerns. (May not apply if you've written your own renderer.)

$3

API Extractor has a particular format required for certain types of doc comments and will fail at build time if this format is not followed. There are also a few suggested best practices.

/**
 * @param myParam - Description here
 */

/**
 * @param myParam Description here
 * @param {number} myParam Description here
 */

/**
 * Comment about > and {.
 * As of version \>= 1.0.0.
 */

/**
 * Comment about '>' and '{'.
 * As of version >= 1.0.0.
 */

/**
 * @deprecated Use foo instead.
 */

/**
 * Deprecated. Use foo` instead.
 * @deprecated
 */

/**
 * @defaultvalue 'hello world'
 */

/**
 * Default is 'hello world'
 */