JSDoc通过标准注释提升JavaScript代码可读性与维护性，支持类型标注、参数说明、示例及异常描述，广泛用于前端与Node.js开发。
在JavaScript开发中，良好的文档是维护代码可读性和团队协作的关键。JSDoc是一种广泛使用的注释语法，能够为JavaScript代码生成结构化的API文档。它不仅提升代码的可理解性，还能被IDE识别，实现智能提示和类型检查。掌握JSDoc的基本规范和常用标签，对前端和Node.js开发者都非常重要。
基本语法与注释结构
JSDoc注释以 /** 开头，每行以星号开头，最后以 */ 结束。支持多种标签（以@开头）来描述函数、参数、返回值等信息。
一个标准的JSDoc注释示例如下：
/*** 计算两个数的和
* @param {number} a - 第一个加数
* @param {number} b - 第二个加数
* @returns {number} 两数之和
*/
function add(a, b) {
return a + b;
}
说明：每行注释前的星号对齐不是强制要求，但保持格式统一更清晰。@param 和 @returns 是最常用的标签。
立即学习“Java免费学习笔记（深入）”；
常用标签详解
JSDoc提供了丰富的标签来描述代码元素。以下是开发中最常使用的几个：
- @param {type} name - description：描述函数参数的类型、名称和说明。类型用花括号包裹，如 {string}、{Array<number>}。
- @returns {type} description：定义函数返回值的类型和说明。也可写作 @return。
- @typedef：用于定义自定义类型，适合复杂对象结构。
- @throws {type} description：标明函数可能抛出的异常类型。
- @example：提供使用示例，帮助理解函数用法。
示例：使用 @typedef 定义用户对象类型：
/**
* @typedef {Object} User
* @property {string} name - 用户名
* @property {number} age - 年龄
*/
/**
* 创建用户欢迎消息
* @param {User} user - 用户对象
* @returns {string} 欢迎语
*/
function welcome(user) {
return `Hello, ${user.name}!`;
}
支持类型标注与现代JS特性
JSDoc支持ES6+语法和类型推断，能与TypeScript兼容。即使不使用TS，也可以通过注释实现类型检查。
- 支持原生类型：{string}、{boolean}、{null}、{undefined}、{any} 等。
- 支持数组：{number[]} 或 {Array.<string>}
- 支持联合类型：{string | number}
- 支持可选参数：@param {string} [name] - 可选的用户名
- 支持默认值：@param {string} [name="guest"] - 带默认值的参数
箭头函数和类方法同样适用JSDoc：
/*** 获取用户信息
* @param {string} id - 用户ID
* @returns {Promise.<User>} 用户信息Promise
*/
const fetchUser = async (id) => {
// ...
};
生成HTML文档与工具集成
可以使用官方工具 jsdoc 从注释生成静态HTML文档。
- 安装：npm install -g jsdoc
- 生成文档：jsdoc yourfile.js -d docs
- 输出结果在docs目录中，包含索引和详细API页面
主流编辑器（VS Code、WebStorm）均支持JSDoc，鼠标悬停即可查看参数提示。配合ESLint或TypeScript，还能实现类型校验，减少运行时错误。
基本上就这些。写好JSDoc不是负担，而是对团队和未来自己的负责。坚持使用，代码质量会明显提升。
