17370845950

新闻动态
文档生成：JSDoc注释规范指南
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}

示例：

/**
 * 获取用户信息
 * @async
 * @param {string} userId - 用户唯一标识
 * @returns {Promise} 用户对象
 * @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;

/**
  • 创建新用户实例
  • @param {string} name - 用户名
*/
constructor(name) {
super();
this.name = name;
}
}
生成与维护文档


可使用工具如 jsdoc、TypeDoc 或 VS Code 插件解析注释并输出 HTML 文档。


建议做法：


    

  • 将文档生成纳入构建流程，定期更新
    • 

  • 在 CI 中校验 JSDoc 完整性（如参数缺失）
    • 

  • 结合 ESLint 使用 eslint-plugin-jsdoc 提高注释质量
    • 

  • 保持注释与代码同步，避免过时描述
    • 



基本上就这些，坚持写清晰的 JSDoc，长期来看能显著降低维护成本。
 
	









            
            

              
              
            

          
        
      
      


  
赣ICP备2024031479号