Component documentation
Put the component's introduction and examples in the JSDoc block above its class. Put property descriptions next to their declarations. The Custom Elements Manifest analyzer extracts this metadata for the reference pages.
Start with the component's purpose, then explain how to use it. Keep implementation steps out of public descriptions unless consumers need them to understand a constraint.
/**
* Triggers an action or links to another page.
*
* @customElement esp-button
* @docPageTitle Button
* @docUrl /components/button
*/
@customElement("esp-button")
export class EspalierButton extends EspalierElementBase {
// Properties and implementation go here.
}
Use the shared component base unless the repository's architecture guidance records an exception. Copy the metadata conventions from a nearby component when adding a new one.
Document the public API
Use the tags appropriate to the API you expose:
| Tag | What to describe |
|---|---|
@prop {type} name - description |
A JavaScript property, including units and accepted values |
@attr {type} name - description |
An HTML attribute and how it affects the component |
@default value |
The initial value |
@slot - description |
Content accepted in the unnamed slot |
@slot name - description |
Content accepted in a named slot |
@fires event-name - description |
A custom event, when it fires, and its payload |
@cssprop --variable-name - description |
A public CSS custom property and its effect |
@csspart part-name - description |
A part consumers may style with ::part() |
Existing components also use @event for event descriptions. Preserve event
names and payload types when editing their prose.
A useful description answers questions the declaration cannot: does an empty value disable a feature? Is a width measured in pixels? Does an event bubble? Does an attribute apply to the host or an inner control?
Write comments for the reader
Use inline code for identifiers and Markdown links to related guides. Prefer a short sentence over a list of bold labels. For implementation comments, explain why a step is needed or which constraint it protects; omit comments that simply repeat the next line of code.
Keep analyzer tags, defaults, and examples intact when editing comments. They are build inputs as well as documentation.
Add examples and verify
Follow interactive examples for snippet syntax. Build the docs using the pipeline guide, then check the rendered API and examples. Follow the repository's test and lint requirements before requesting review.