X Tutup
Skip to content

Latest commit

 

History

History

api-docs

README.md

@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.
/**
 * Comment about the props
 * {@docCategory Foo}
 */
interface FooProps {}

  1. 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.)

  2. 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.

const { generatePageJsonFiles } = require('@fluentui/api-docs');
const config = {}; // your config here
generatePageJsonFiles(config);
  1. 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

Supported API items

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

Markdown

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.)

Prop comments

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.

Good Bad
@param tags must include a dash and not contain type information 
/**
 * @param myParam - Description here
 */
 
/**
 * @param myParam Description here
 * @param {number} myParam Description here
 */
Special characters which have meaning in TSDoc (e.g. @ > { }) must be escaped with backslashes or backticks 
/**
 * Comment about `>` and `{`.
 * As of version \>= 1.0.0.
 */
 
/**
 * Comment about '>' and '{'.
 * As of version >= 1.0.0.
 */
@deprecated tags should include a deprecation message 
/**
 * @deprecated Use `foo` instead.
 */
 
/**
 * Deprecated. Use `foo` instead.
 * @deprecated
 */
Default values should be indicated by @defaultvalue tags (@default and @defaultValue also work) 
/**
 * @defaultvalue 'hello world'
 */
 
/**
 * Default is 'hello world'
 */
X Tutup