JsDoc生成文档时渲染完整代码而非注释块的问题如何解决

JsDoc默认启用了源码展示配置，生成HTML文档时会自动附加对应文件的完整源码内容，属于工具默认行为，并非操作步骤出错。

• 核心配置修改：在你的jsdocrc.json配置文件中添加如下配置项，关闭源码输出开关：

{
  "templates": {
    "default": {
      "outputSourceFiles": false
    }
  }
}

如果没有自定义配置文件，可以在项目根目录新建该文件，执行生成命令时指定配置文件即可生效：jsdoc [JS文件路径] -c jsdocrc.json

• 注释规范补充：给需要生成文档的代码块添加标准JsDoc标记，明确标注需要纳入文档的内容，避免不必要的代码被识别收录，示例写法：

/** 
 * This is a description of the foo function. 
 * @function myfunction
 * @public
 */
function myfunction() {
  alert('hello world');
}
/** @ignore */
console.log(myfunction);

给不需要生成文档的代码加上@ignore标记，JsDoc会直接跳过该部分内容的解析

• 版本校验：如果配置不生效可以检查全局JsDoc版本，3.6.0以上版本均支持上述配置，可执行npm update jsdoc -g升级到最新稳定版后重试

内容的提问来源于stack exchange，提问作者Facundo Salas