在JavaScript开发中，使用JSDoc注释规范能够让我们以统一的方式描述代码的结构与用途，并借助工具自动生成专业的API文档。JSDoc是一套基于注释的文档系统，通过在函数、类、变量上方书写特定格式的多行注释，就可以清晰表达类型、参数和返回值等信息。
JSDoc基础注释结构
JSDoc注释以斜杠加两个星号开头，以星号加斜杠结束。在注释块内部，使用以@开头的标签来标记元数据。最常见的标签包括@param和@returns。
描述一个简单函数
下面示例展示如何为一个计算两数之和的函数编写注释：
/**
* 计算两个数字的和
* @param {number} a - 第一个加数
* @param {number} b - 第二个加数
* @returns {number} 返回相加结果
*/
function add(a, b) {
return a + b;
}
常用JSDoc标签说明
除了基础标签，还有一些标签在复杂项目中非常实用。下表列出部分常用标签及其作用：
| 标签 | 用途 |
|---|---|
| @param | 描述函数参数及类型 |
| @returns | 描述返回值类型与含义 |
| @typedef | 定义复杂类型或对象结构 |
| @class | 标记一个类定义 |
使用typedef描述对象类型
当函数接收或返回的是一个对象时，可以用@typedef先声明结构：
/**
* @typedef {Object} User
* @property {string} name - 用户姓名
* @property {number} age - 用户年龄
*/
/**
* 打印用户信息
* @param {User} user - 用户对象
*/
function printUser(user) {
console.log(user.name + ' ' + user.age);
}
生成文档的方法
编写好JSDoc注释后，可以使用官方提供的jsdoc命令行工具扫描源码并输出HTML文档。在项目目录下执行如下命令即可：
npm install -g jsdoc jsdoc app.js -d docs
上述命令会将app.js中的注释生成为docs文件夹下的网页文件。团队可以将这些文件部署到内部站点，方便随时查阅接口说明。
注释编写建议
- 为每个对外暴露的函数和类写@param与@returns
- 使用真实类型名称，避免写any之类模糊描述
- 在公共库中使用@typedef统一复杂结构
- 注释语言保持简洁，说明意图而非重复代码
遵循JSDoc规范后，新成员可以通过生成的文档快速理解项目，也能减少沟通中的误解。把注释当作代码的一部分来维护，长期看会显著降低维护成本。
JavaScriptJSDoc文档生成注释规范代码注释修改时间：2026-07-24 16:03:26