JSDoc是否识别成员赋值？如何隐藏私有成员生成文档？

首先明确你的场景：你把核心逻辑放在私有模块lib/private.js里，通过lib/index.js导出公开函数，但遇到两个问题：

• 直接运行jsdoc lib/index.js没有生成任何文档
• 运行jsdoc lib会把私有模块里的internalFunc也显示出来，不符合隐藏私有成员的需求
  而且你不想把private.js里的文档复制到index.js里——这完全可以通过JSDoc的标记和配置来解决。

解决方案1：用@alias关联私有函数到公开导出 #

这是最直接的方法，不用修改太多代码，只需要在private.js的函数注释里加上@alias标记，把它和公开导出的函数绑定：

修改lib/private.js的代码：

/**
 * My private function
 *
 * @param {string} foo some foo
 * @return {number} bar value
 * @alias module:lib.publicFunc
 */
exports.internalFunc = foo => 42;

这里的module:lib.publicFunc对应index.js导出的publicFunc（lib是模块根目录，因为index.js是入口）。

之后运行jsdoc lib/index.js，JSDoc就会把internalFunc的文档关联到publicFunc上，生成正确的公开函数文档。

解决方案2：配合配置文件排除私有模块 #

如果你不想让JSDoc扫描私有模块，可以创建一个jsdoc.json配置文件，指定只处理公开入口，排除私有文件：

{
  "source": {
    "include": ["lib/index.js"],
    "exclude": ["lib/private.js"]
  },
  "opts": {
    "destination": "./docs"
  }
}

运行命令：

jsdoc -c jsdoc.json

注意：这个方法需要和解决方案1配合，否则index.js里只有导出语句，没有文档注释，JSDoc还是生成不了内容。

解决方案3：用@ignore隐藏私有函数 #

如果需要扫描整个lib目录但不想显示私有成员，可以给private.js里的internalFunc加上@ignore标记，同时用@alias关联到公开导出：

/**
 * My private function
 *
 * @param {string} foo some foo
 * @return {number} bar value
 * @alias module:lib.publicFunc
 * @ignore
 */
exports.internalFunc = foo => 42;

然后运行jsdoc lib，JSDoc会忽略internalFunc的独立文档，但会把它的内容关联到publicFunc上，最终只显示公开函数的文档。

解决方案4：用@see引用私有函数文档 #

如果你不想修改私有模块的注释，可以在index.js里给导出的publicFunc加一个@see标记，指向私有函数的文档：

/**
 * @see module:lib/private.internalFunc
 */
exports.publicFunc = require('./private').internalFunc;

然后给private.js里的internalFunc加上@ignore标记，运行jsdoc lib后，publicFunc的文档会显示指向私有函数的引用，同时私有函数本身不会出现在最终文档里。

总结 #

最推荐的组合是解决方案1 + 解决方案3：用@alias把私有函数的文档绑定到公开导出，再用@ignore隐藏私有成员，这样既不用重复写文档，又能精准控制生成的内容。

内容的提问来源于stack exchange，提问作者Franklin Yu