JavaScript注释规范

JSDoc 是一个针对 JavaScript 的 API 文档生成器，它通过特定格式的注释来生成结构化的 API 文档。使用 JSDoc 可以帮助开发者更好地理解代码、提高代码可读性和可维护性。

注释基础

基础语法

JSDoc 使用以 /** 开始、以 */ 结束的块级注释：

/**
 * 这里是注释内容
 */

标签

JSDoc 使用各种特殊标记（以 @ 开头）来描述代码的不同方面。这些标记可以单独使用，也可以组合使用。

文件与元信息

@file

描述当前文件的用途和内容。

/**
 * @file 文件描述
 */

@author

描述作者信息。

/**
 * @author 作者信息 <邮箱>
 */

@license

描述许可证信息。

/**
 * @license MIT
 */

@version

描述版本信息。

/**
 * @version 1.0.0
 */

@copyright

描述版权信息。

/**
 * @copyright 版权信息
 */

@see

提供相关信息的引用链接。

/**
 * @see 参考信息 {@link 参考信息链接}
 */

@todo

标记待办事项或未来计划。

/**
 * @todo 待办信息
 */

@description

添加详细描述信息。

/**
 * @description 注释描述
 */

可见性与结构

@class

描述类信息。

/**
 * 描述类信息
 * @class
 */
class Person {}

@private / @protected / @public

标记成员的可见性级别（无需与 TypeScript 配合也可用于文档生成）。

/** @private */
function internalHelper() {}

/** @protected */
class Base {
  /** @protected */ method() {}
}

/** @public */
function exposed() {}

@typedef 与 @property

定义结构化类型，方便在 @param、@returns 等标签中复用。

/**
 * 用户信息
 * @typedef {object} User
 * @property {number} id 用户 ID
 * @property {string} name 用户名
 * @property {('admin'|'user')} role 角色
 */

/**
 * 获取用户
 * @returns {User} 用户对象
 */
function getUser() {
  return { id: 1, name: 'Alice', role: 'admin' };
}

类型与函数

@type

描述变量的类型信息。

/**
 * 变量含义
 * @type {类型}
 */

/**
 * 一个字符或数字类型的变量
 * @type {(string|number)}
 */

/**
 * 类型为数字或空
 * @type {(?number)}
 */

/**
 * 类型为数字且不能为空
 * @type {(!number)}
 */

/**
 * 类型不做限制
 * @type {*}
 */

@function

明确标记一个函数。

/**
 * @function 函数描述
 */

参数、返回与错误

@param

描述函数参数信息。

/**
 * @param {参数类型} 参数名称 参数描述
 */

/**
 * @param {number} a 数字
 * @param {number} b 数字
 */
function add(a, b) {}

/**
 * @param {number} a 数字
 * @param {number} [b=1] 数字, 默认值1
 */
function add(a, b) {}

/**
 * @param {*} param 参数不做类型限制
 */
function add(param) {}

@return

描述函数返回值信息（与 @returns 同义）。

/**
 * 两个数字相加
 * @param {number} a 数字
 * @param {number} b 数字
 * @return {number} a + b 的结果
 */
function add(a, b) {
  return a + b;
}

@returns

描述函数返回值信息（推荐使用 @returns）。

/**
 * 计算两个数之和
 * @param {number} a 第一个数
 * @param {number} b 第二个数
 * @returns {number} 相加结果
 */
function add(a, b) {
  return a + b;
}

@throws

描述函数可能抛出的异常类型与原因。

/**
 * 解析 JSON 字符串
 * @param {string} text JSON 文本
 * @returns {object} 解析后的对象
 * @throws {SyntaxError} 当文本不是合法 JSON 时抛出
 */
function parseJson(text) {
  return JSON.parse(text);
}

@async

标记函数为异步函数；通常与 @returns {Promise<类型>} 结合使用。

/**
 * 获取数据
 * @async
 * @returns {Promise<string>} 服务端响应
 */
async function fetchData() {
  return 'ok';
}

示例

@example

提供代码使用示例。

/**
 * 两个数字相加
 * @param {number} a 数字
 * @param {number} b 数字
 * @return {number} a + b 的结果
 *
 * @example
 * add(1, 2) // 3
 */
function add(a, b) {
  return a + b;
}

其他辅助

@deprecated

标记 API 已废弃，并可提供替代方案。

/**
 * @deprecated 请改用 newApi()
 */
function oldApi() {}