liveBook · Manning

JSDoc

As explained in Web Component Development with Modern Libraries and Tooling

JSDoc is a documentation-generation tool and comment syntax for producing API documentation from JavaScript source annotations.

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

@attr {type} <name>

attribute documentation for HTML authors;
alias @attribute

@cssprop --<name>[=<value>]

CSS custom property that affects component styling; alias @cssproperty

@fires <event-name>

event that can be dispatched; alias @event

@part <part-name>

shadow DOM part that can be styled; alias @csspart

@prop {type} <name>

property documentation for JavaScript developers;
alias @property

@slot <name>

default or named slot whose content can be supplied

@summary <description>

single-line description that summarizes the longer description preceding the JSDoc tags

@tag <tag-name>

custom element name; alias @tagname

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

How Web Component Development with Modern Libraries and Tooling covers it

How deep it goes
Explains syntax conventions and class, field, and method tags, then demonstrates a complete component annotation without covering every supported tag.
Examples
Uses a HelloWorld custom element with attributes, properties, slots, CSS properties, a CSS part, and generated CEM metadata.
What it assumes
Assumes JavaScript source and comments, while teaching the annotation tags needed to describe web component APIs.
What you can do after
Apply it via JSDoc comments to describe component APIs and generate metadata for documentation, editors, and Storybook.
How it connects
Connects JSDoc with web components, Custom Elements Manifest, API documentation, IDE IntelliSense, and Storybook.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Web Component Development with Modern Libraries and Tooling. The section links point to the parts of the book it draws on.