Complete documentation for stencil components with jsdoc, specifically a component description?

Question

I'm in the process of creating a web components library with stencil.js. I would like to leverage the docs-readme output capability, but am having to do a lot of trial and error on what comments will actually be output into the documents.

The specific issue I'm having right now is that I'm not able to get documentation for the component itself to generate with the readme. For example:

/**
 * This is a description of the component that I would like to generate in the readme.md for MyComponent
 */
@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',  
  shadow: true,
})
/** I've also tried this comment style and this location, but no dice */
export class MyComponent {
   ...
}

According to the jsdoc documentation it seems like I should be able to document the class, but nothing seems to work. Is there an exhaustive list of what stencil will and won't actually generate documentation for?

Answer 1

You need to place the documentation of the web component (element class) itself to the (partially) generated readme.md. Only the documentation of the class members (properties/attributes, methods) and of the CSS variables is expected in the source files (.tsx, .css).

(Update: See the UPDATE section below about the purpose of the component comment.)

Insert the documentation to src/components/my-component/readme.md above the following line:

<!-- Auto Generated Below -->

The content below this line will be generated using the JSDoc comments in your source files.

Example

# x-eyes

Shows a pair of eyes following movements of ...

<!-- Auto Generated Below -->

See the full readme, TS source and CSS source of the example above.

UPDATE

Actually, if you add a documentation comment to the component as you intended:

/**
 * Alternative summary...
 */
@Component({ tag: 'x-eyes', styleUrl: 'x-eyes.css' })
export class XEyesElement {

it will be used, but not in the readme file; but only in the docs property of the docs-json or docs-vscode output targets:

{
  "filePath": "./src/components/x-eyes/x-eyes.tsx",
  "encapsulation": "shadow",
  "tag": "x-eyes",
  "docs": "Alternative summary...",
  "readme": "# <x-eyes>\n\nShows a pair of eyes following movements ...

If you do not add the documentation comment to the component, the content of the docs property will be extracted from the first part of your readme.md, between the main title and the first sub-title (initiated by #):

{
  "filePath": "./src/components/x-eyes/x-eyes.tsx",
  "encapsulation": "shadow",
  "tag": "x-eyes",
  "docs": "Shows a pair of eyes following movements of ...",
  "readme": "# <x-eyes>\n\nShows a pair of eyes following movements ...

So, if you want to change the description summary of your component to be shorter or different than the introductory part of your readme.md, you can insert the component comment to your component source.