How to document Lightning Web Components (LWCs)?

Question

Aura Component bundles can include a .auradoc file that in itself is well documented. For Lightning Web Components, the bundle is stripped down to less files which is a good thing. And the overall Salesforce provided documentation for both is now excellent and must have taken a lot of work to create.

I'm looking for a way to provide some basic documentation on a set of LWCs that is written by the developers rather than a technical writer. What is a good way to do that?

Answer 1

We use JSDoc on the JavaScript file to document the component like this (which follows the copyright notice at the top of the file then the imports):

The template simply includes our copyright notice (as does the CSS file).

Exactly what this looks like when generated entirely depends on the JSDoc tool you use to generate your output. Within IDEA it is rendered as, for example:

You can use something like jsdoc.app for the documentation generation, for example.

Answer 2

As also suggested in the accepted answer already, JSDoc can be seen as the standard for code documentation in JavaScript. Therefore it is also a suitable solution for Lightning Web Components.

Use JSDoc comments in LWC

For example, a correctly annotated Hello World LWC could look like this:

import { api, LightningElement } from 'lwc';

/**
 * An example LWC that adds a classic greeting to any page.
 * @alias HelloWorld
 * @extends LightningElement
 * @hideconstructor
 *
 * @example
 * <c-hello-world name="World"></c-hello-world>
 */
export default class HelloWorld extends LightningElement {
  /**
   * Enter the name of the person to greet.
   * @type {string}
   * @default 'World'
   */
  @api name = 'World';
}

Generate LWC code documentation

If you have properly annotated your components as just shown, you can even generate a well-formatted document using jsdoc.app.

To do this, you must first install the appropriate node package, for example globally as follows:

npm install -g jsdoc

Furthermore, a jsdoc.config.json file must be located in the root directory of the project, which may look like the following:

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "source": {
    "include": ["force-app/main/default/lwc"],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": [],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  },
  "opts": {
    "destination": "docs",
    "recurse": true,
    "readme": "README.md"
  }
}

Then the documentation can be generated as follows:

jsdoc -c jsdoc.config.json

Setup guide

I also published a short guide on how to use JSDoc for Lightning Web Components with step by step instructions and more detailed explanations, this could additionally help anyone trying to use it:

Write and generate LWC code documentation using JSDoc