如何使 jsdoc 实际输出文档？

Question

我正在尝试让 jsdoc（版本 3.6.7，使用节点 16）将我记录的 js 代码变成实际的文档，但无论我做什么它只会生成一个 out 目录，其中 index.html 主要是空行，而不是文档。我已经在 the issue tracker 上询问过这个问题（在我搜索文档和网络以获取关于让 jsdoc 生成空文件可能做错了什么的信息之后，但我终生无法找到解决这个问题的任何有用的东西）但是因为已经过去了几天，所以在这里提问也很有用，这样任何一个地方的答案都可以交叉发布。

运行 jsdoc 命令不会标记任何输入错误，并以正常的零退出代码完成，但不会生成任何有用的东西，所以希望这里有人运行到他的before 并且可以解释除了下面的代码之外还需要什么才能实际获取jsdoc来生成文档。

根据 jsdoc 没有错误的代码示例，但也不会产生任何文档：

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

/**
 * Several paragraphs of text that explain this class
 *
 * @class
 * @namespace model
 */
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.
   *
   * @ignore
   */
  constructor(caller, when) {
    if (!caller || typeof when !== "number") {
      const { name } = this.__proto__.constructor;
      throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
    }
  }
}

运行这与 jsdoc test.js 产生一个 out 目录与 index.html 和 test.js.html 文件，第一个包含大约三十行“没有文档”这里”带有样板包装器 HTML 代码，第二个包含原始源代码，没有其他有用的东西。

还需要做什么才能让 jsdoc 在这里实际生成文档？

Answer 1

我已经通过不使用类前面的 export 而是在文件末尾导出它们来修复它。像这样：

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

/**
 * Several paragraphs of text that explain this class
 *
 * @class
 * @namespace model
 */
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.
   *
   * @ignore
   */
  constructor(caller, when) {
    if (!caller || typeof when !== "number") {
      const { name } = this.__proto__.constructor;
      throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
    }
  }
}

export {Model}

Answer 2

原来发布得太早了：花时间从 classes 的官方文档开始 https://jsdoc.app/tags-class.html 和运行那个通过 jsdoc 的例子工作得很好，然后构建该示例以匹配实际文件的代码，也可以很好地生成工作文档。

在这个具体案例中，存在几个问题：

添加 @namespace 与 @class 配对是主要问题。两者都不是必需的，但是 @namespace 条目改变了 jsdoc 解析文件文档其余部分的方式，如果要显示方法，它们必须使用包含该命名空间的 @name 属性。由于此处情况并非如此，因此文档中最终没有显示任何内容。
在 class 上有一个 @ignore on the constructor function, rather than using the @hideconstructor 属性意味着即使删除了 @namespace，也没有编写任何文档。 JSdoc 将 class 文档标题和构造函数视为同一事物，因此 @ignore 构造函数被视为与忽略整个 class.

修正这两个错误，并删除顶部不必要的 @class，提供完美的文档：

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);
    }
  }
}

如何使 jsdoc 实际输出文档？

How does one make jsdoc actually output docs?

jsdoc