如何让 jsdoc 实际输出文档？

Question

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

运行jsdoc 命令不会标记任何输入错误，并以正常的零退出代码完成，但不会产生任何有用的信息，因此希望这里有人遇到过他的问题，并且可以解释除了以下内容之外还需要什么实际获取 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 运行此程序会产生一个带有index.html 和test.js.html 文件的out 目录，第一个包含大约30 行“这里没有文档”和样板包装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

事实证明这发布得太早了：花时间从 https://jsdoc.app/tags-class.html 上的类的官方文档开始并通过 jsdoc 运行该示例非常好，随后构建该示例以匹配实际文件的代码产量工作文档也很好。

在这个特定的案例中，有几个问题：

1. 添加@namespace 和@class 是主要问题。两者都不是必需的，但是 @namespace 条目改变了 jsdoc 解析文件文档其余部分的方式，如果要显示方法，它们必须使用包含该命名空间的 @name 属性。由于此处并非如此，因此文档中最终没有显示任何内容。

2. 在构造函数上使用@ignore，而不是在类上使用@hideconstructor 属性意味着即使删除了@namespace，也没有编写任何文档。 JSdoc 将类文档标题和构造函数视为同一事物，因此 @ignoreing 构造函数被视为忽略整个类。

修复这两个错误并删除顶部不必要的@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);
    }
  }
}