使用jsdoc 3.6.7生成空文档，如何操作才能输出有效说明文档

问题根因 #

该问题由两个常见错误共同导致：

• JSDoc 3.6.7默认未开启ES模块语法支持，无法识别export导出的类定义
• 类注释同时使用@class和@namespace标签产生语义冲突，导致JSDoc无法将类归入正确的文档结构

具体修复操作 #

1. 修正注释标签冲突 #

删除类注释中的@namespace标签，该标签仅适用于模块、普通对象等命名空间场景，不能和@class同时作用于类定义。

2. 开启ES模块支持 #

在项目根目录创建jsdoc.json配置文件，写入以下内容：

{
  "source": {
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(node_modules/|docs)"
  },
  "sourceType": "module",
  "opts": {
    "destination": "./docs/",
    "recurse": true
  }
}

其中"sourceType": "module"配置项会开启ES模块语法解析支持，让JSDoc正确识别export导出的内容。

3. 明确绑定静态方法归属 #

为了避免赋值式的静态方法识别异常，可以在该方法的注释中加入@memberof Model标签，明确指定该方法属于Model类。

修改后的完整示例代码 #

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

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

  /**
   * Also several paragraphs explaining the use of this function.
   *
   * @static
   * @memberof Model
   * @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：

jsdoc -c jsdoc.json test.js

生成的文档会保存在配置中指定的./docs目录下，可正常显示类和方法的所有注释内容。

内容的提问来源于stack exchange，提问作者Mike 'Pomax' Kamermans