How to document LWC Salesforce components public variables with JSDoc?

Question

JSDoc skips my public LWC variables. Here is an example:

    /**
     * SomePublicVarName mode - default is false.
     * 
     * @type {boolean}
     */
    @api 
    somePublicVarName = false;

If I convert that to a function or a public getter/setter, then I can see it in the output. Is there a way around that? Can I change JSDoc parsing behavior? I read in the docs I can use a configuration file, but I don't know if this is a use case for it. I also tried to add the @public JSDoc property hopping that would fix the issue, but it didn't help.

Answer 1

It pulls the public properties as long as the class is documented as well. I've used alias as it'll show as export if you don't add one and I've added hideconstructor to remove it showing new exports().

import { LightningElement,api } from 'lwc';
/**
 * An example of a LWC documented with jsdoc
 * @alias JsDocExampleLWC
 * @hideconstructor
 */
export default class JsDocExample extends LightningElement {
    /**
     * @type {boolean}
     */
    @api someProp; 
}

Answer 2

Proper use of JSDoc comments in LWC

As also suggested in the accepted answer already, you need to take care of the correct class documentation as well. 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

After you have properly annotated your components as just shown, you can 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 initially had the same difficulties. Therefore, I also published a short guide on how to properly use JSDoc for Lightning Web Components with step by step instructions and more detailed explanations, this could help anyone trying to use it:

Write and generate LWC code documentation using JSDoc