JSDoc 是一种为 JavaScript 提供结构化注释的标准，通过使用如 @param、@returns、@example 等标签提升代码可读性和维护性；它支持函数、类、属性的详细文档化，并可通过工具生成 HTML 文档，结合 ESLint 和 CI 流程确保注释质量，有效促进团队协作与项目长期维护。
JSDoc 是一种用于为 JavaScript 代码添加结构化注释的文档标准，它不仅能提升代码可读性，还能配合工具自动生成 API 文档。遵循统一的 JSDoc 注释规范，有助于团队协作和后期维护。以下是实用的 JSDoc 注释编写指南。
基础语法与常用标签
JSDoc 注释以 /** 开头，每行以 * 对齐，使用特定标签描述代码元素。常见标签包括：
- @param {类型} 参数名 - 描述参数用途
- @returns {类型} - 描述返回值
- @example - 提供使用示例
- @throws {错误类型} - 说明可能抛出的异常
- @deprecated - 标记已弃用的方法
例如：
/**
* 计算两个数的和
* @param {number} a - 第一个加数
* @param {number} b - 第二个加数
* @returns {number} 两数之和
* @example
* add(2, 3); // 返回 5
*/
function add(a, b) {
return a + b;
}
函数与方法注释规范
每个公开函数或类方法都应包含 JSDoc 注释，明确其行为边界。
注意点：
- 必须注明所有参数类型和含义，即使类型简单
- 返回值类型不可省略，void 类型也需标注 {@link void}
- 若函数有副作用（如修改全局变量），应在描述中说明
- 异步函数返回值应标注为 {Promise<T>}
示例：
/**
* 获取用户信息
* @async
* @param {string} userId - 用户唯一标识
* @returns {Promise<Object>} 用户对象
* @throws {Error} 网络请求失败时抛出
*/
async function fetchUser(userId) {
const res = await fetch(`/api/users/${userId}`);
if (!res.ok) throw new Error('Failed to fetch');
return res.json();
}
类与属性文档化
类定义应使用 @class 或 @constructor 标注，属性建议使用 @property。
- 私有成员可用 @private 标识
- 静态成员使用 @static
- 继承关系可通过 @extends 表达
示例：
/**
* 用户模型类
* @class
* @extends {BaseModel}
*/
class User extends BaseModel {
/**
* 用户名称
* @type {string}
* @property
*/
name;
<p>/**</p><ul><li>创建新用户实例</li><li>@param {string} name - 用户名
*/
constructor(name) {
super();
this.name = name;
}
}生成与维护文档
可使用工具如 jsdoc、TypeDoc 或 VS Code 插件解析注释并输出 HTML 文档。
建议做法：
- 将文档生成纳入构建流程，定期更新
- 在 CI 中校验 JSDoc 完整性（如参数缺失）
- 结合 ESLint 使用 eslint-plugin-jsdoc 提高注释质量
- 保持注释与代码同步，避免过时描述
基本上就这些，坚持写清晰的 JSDoc，长期来看能显著降低维护成本。
