[Solved] How does one make jsdoc actually output docs?

by


Turns out this was posted too early: taking the time to start at the official documentation for classes over on https://jsdoc.app/tags-class.html and running that example through jsdoc works perfectly fine, and subsequently building out that example to match the actual file’s code yields working documentation just fine, too.

And in this specific case, there were several problems:

  1. adding @namespace paired with @class was the main problem. Neither were necessary, but the @namespace entry changes how jsdoc parses the rest of a file’s documentation, where if methods are to show up, they must use a @name property that includes that namespace. As that was not the case here, nothing ended up showing in the documentation.

  2. having an @ignore on the constructor function, rather than using the @hideconstructor property on the class meant that even with @namespace removed, no documentation got written. JSdoc treats the class docs heading and the constructor as the same thing, so @ignoreing the constructor is treated the same as ignoring the entire class.

Fixing both mistakes, and removing the unnecessary @class at the top, gives perfectly fine documentation:

import { Errors } from "../errors.js";
import { Models } from "./models.js";

/**
 * Several paragraphs of text that explain this class
 *
 * @hideconstructor
 */
export class Model {
  /**
   * @ignore
   */
  static ALLOW_INCOMPLETE = Symbol();

  /**
   * Also several paragraphs explaining the use of this function.
   *
   * @static
   * @param {*} data
   * @param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
   * @returns {*} a model instance
   * @throws {*} one of several errors
   */
  static create = function (data = undefined, allowIncomplete) {
    return Models.create(
      this,
      data,
      allowIncomplete === Model.ALLOW_INCOMPLETE
    );
  };

  /**
   * code comment that explains that if you're reading
   * this source, you should not be using the constructor,
   * but should use the .create factory function instead.
   */
  constructor(caller, when) {
    if (!caller || typeof when !== "number") {
      const { name } = this.__proto__.constructor;
      throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
    }
  }
}

solved How does one make jsdoc actually output docs?