文档生成：JSDoc注释规范指南-js教程-PHP中文网

文档生成：JSDoc注释规范指南

狼影

发布： 2025-11-23 21:39:06

原创

539人浏览过

JSDoc 是一种为 JavaScript 提供结构化注释的标准，通过使用如 @param、@returns、@example 等标签提升代码可读性和维护性；它支持函数、类、属性的详细文档化，并可通过工具生成 HTML 文档，结合 ESLint 和 CI 流程确保注释质量，有效促进团队协作与项目长期维护。

文档生成：jsdoc注释规范指南

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。

DoitPHP编码规范

DoitPHP编码规范基于PHP PEAR编码规范及PHPDocumentor注释规范等编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。以达事半功倍的效果。为了与时俱进，根据客观需求，本文档会不定期更新。作者：tommy

262

查看详情

私有成员可用 @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;
}
}

登录后复制