JSDoc is a markup language written inside JavaScript comments delimited by /** and */. Documentation tools read these annotations to generate API documentation and related metadata for web components. section 10.2 section 1.5
For a component, annotations describe the custom-element tag, attributes, properties, slots, CSS custom properties, CSS parts, events, fields, and methods. These details can feed Custom Elements Manifest files and supporting tools. section 10.2 section 1.5
Common annotations include:
- @tag names the custom element; @summary supplies a short description. section 10.2
- @attr documents an HTML attribute, while @prop documents a JavaScript property and its type. section 10.2
- @slot describes supplied content; @cssprop and @part describe styling extension points. section 10.2
- @param and @returns document method inputs and results; @deprecated marks an API planned for removal. section 10.2
Documenting a greeting component
A HelloWorld component can describe its public API with a single class comment: /** * This displays a greeting message for a given name in a specified color. * @summary This displays a greeting message. * @tag hello-world * @attr {string} color - initial text color * @attr {string} name - initial name to greet * @prop {string} [color=black] - current text color * @prop {string} [name=World] - current name to greet * @slot - for content after the greeting * @slot before - for content before the greeting * @cssprop [--border-color=gray] color of border that surrounds the component * @part greeting - greeting message */ The annotations expose both author-facing HTML attributes and developer-facing properties, including defaults and styling hooks. section 10.2
Table 10.1 JSDoc tags for classes
| Tag | Description |
|
attribute documentation for HTML authors; |
|
CSS custom property that affects component styling; alias |
|
event that can be dispatched; alias |
|
shadow DOM part that can be styled; alias |
|
property documentation for JavaScript developers; |
|
default or named slot whose content can be supplied |
|
single-line description that summarizes the longer description preceding the JSDoc tags |
|
custom element name; alias |
Use the tag reference to match each component feature with its JSDoc annotation and accepted value format. section 10.2
A tool such as @custom-elements-manifest/analyzer can turn annotated source into a CEM file containing component descriptions, attributes, properties, slots, styling details, and events. Editors can use that metadata for help pop-ups and IntelliSense, while Storybook can display documentation and controls. section 1.5 section 10.2
