This topic covers the documentation process for just the public API part, that is what the end-user of the library should use and what is considered stable from the authors' point of view.

Of course, code comments are expected in places, where the purpose of the code is not clear and easily discerned. In other words, this does not free you from documenting private API/implementation details.

The documentation tool uses a combination of analyzing the code of the component and JSDoc tags. The recognized tags and the format which the tool expects can be browsed here.

You don't need to explicitly decorate properties/attributes/methods for type information as the library is written in TypeScript. Correctly typing your methods and properties will be enough for the analyzer to deduce everything it needs.

There are several corner cases which may need additional "manual" work from the author of the component.

1. Certain member of a component needs to be publicly accessible but it should not show in generated documentation. Hopefully rarely needed, but in case you can use the @private tag to hide it from the generated documentation.

   /** @private */
   public someProp: string;

2. This is a scenario mainly for the Storybook part of the process. Some attributes of a web component have no default values. However you may want to provide a default value for the sample in the Storybook browser. In that case use the @attr [attr=value] format for the attribute and it will be reflected in the generated story file.

   /**
    * The label of the control.
    * @attr [label=Default]
    */
   @property()
   label!: string;

npm run build:docs:json

Builds the JSON metadata for each documented component in the source directory. Runs automatically when you start the Storybook preview or you build the package.

npm run build:docs:md

Builds the markdown metadata for each documented component in the source directory.

Hint: Very useful for writing the API part of a specification of a component. Create a proof of concept, document it and run this command.

npm run build:docs:schema

Generates the Custom Element Manifest for the package.

build:docs:vscode-schema

Generates the VSCode custom data manifest. More info here. For how to test and use it here.