jsDoc是一种javaScript文档标准，通过在代码中添加结构化注释并使用工具解析，可生成html格式的API文档。开发者使用@param、@returns等标签描述函数参数、返回值等信息，类似Java注解效果。安装jsdoc工具后，运行命令如jsdoc src/*.js -d docs即可生成文档。结合package.json脚本和CI/CD流程可实现自动化更新，提升代码可维护性与团队协作效率。

javascript本身不支持类似Java的“注解”（Annotation）语法，但通过使用JSDoc这样的文档注释规范，可以实现类似注解的效果，并自动生成结构清晰的API文档。开发者在代码中添加特定格式的注释，再借助工具解析这些注释，生成HTML格式的API文档。

什么是JSDoc

JSDoc是一种广泛使用的JavaScript文档标准，它允许你在函数、类、变量等代码元素上方添加结构化注释。这些注释可以被工具识别并提取，用于生成静态API文档。

例如：

/** * 计算两个数的和 * @param {number} a – 第一个加数 * @param {number} b – 第二个加数 * @returns {number} 两数之和 */ function add(a, b) { return a + b; }

上面的注释中，@param 和 @returns 就是JSDoc的“标签”，它们起到了类似“注解”的作用，描述了函数的行为和参数类型。

使用JSDoc生成API文档的步骤

要基于JSDoc注释生成API文档，可以按照以下流程操作：

Calliper 文档对比神器

文档内容对比神器

28

查看详情

• 安装JSDoc工具：通过npm全局安装JSDoc

npm install -g jsdoc

• 编写带JSDoc注释的JS代码：确保关键函数、类、模块都有完整的JSDoc注释
• 运行生成命令：在项目根目录执行

jsdoc your-file.js

或指定多个文件和输出目录：

jsdoc src/*.js -d docs

• 查看生成的文档：默认会在指定目录（如docs）生成HTML页面，可在浏览器中打开index.html查看

常用JSDoc标签说明

以下是一些常用的JSDoc标签，帮助你更完整地描述API：

• @param {type} name – description：描述函数参数
• @returns {type} description：描述返回值
• @example：提供使用示例
• @class：标识构造函数或es6类
• @Property {type} name – description：描述对象或类的属性
• @throws {ErrorType}：说明可能抛出的异常

集成到开发流程中

为了保持文档与代码同步，建议将文档生成集成到构建流程中。比如：

• 在package.json中添加脚本：

“scripts”: { “doc”: “jsdoc src/*.js -d docs” }

• 结合CI/CD，在代码提交后自动更新文档站点
• 使用ide插件（如vscode的JSDoc插件）快速生成模板注释

基本上就这些。只要坚持写规范的JSDoc注释，就能轻松实现JavaScript API文档的自动化生成，提升团队协作效率和代码可维护性。