当前位置：首页 > article >正文

js 文档注释

article 2025/1/5 14:31:23

在 JavaScript 中，文档注释（也叫 JSDoc 注释）是一种用于为代码提供结构化说明的注释方式。JSDoc 注释通常用于生成 API 文档、提高代码可读性，并为 IDE 提供智能提示。下面是如何在 JavaScript 中编写文档注释的基本指南。

基本语法

JSDoc 注释通常以 /** 开始，并以 */ 结束。每个注释块可以包含不同的标签（tag），用于描述函数、变量、类、参数等内容。

示例：

/**
 * 计算两个数的和。
 * 
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 返回两数的和
 */
function add(a, b) {
  return a + b;
}

常见的 JSDoc 标签

@param
用于描述函数参数。它有两个部分：类型和参数名，以及对该参数的描述。

/**
 * 设置用户的年龄
 * @param {number} age - 用户的年龄
 */
function setAge(age) {
  this.age = age;
}

@returns 或 @return
用于描述函数的返回值。它也有两个部分：返回值的类型和返回值的描述。

/**
 * 获取用户的名字
 * @returns {string} 返回用户的名字
 */
function getName() {
  return this.name;
}

@type
用于指定变量的类型。

/** @type {string} */
let message = "Hello, World!";

@description
用于描述函数、类或方法的行为，可以是对某一功能的详细解释。

/**
 * 这个函数会检查一个数是否为质数。
 * @param {number} num - 要检查的数字
 * @returns {boolean} 如果是质数返回 true，否则返回 false
 */
function isPrime(num) {
  if (num <= 1) return false;
  for (let i = 2; i < num; i++) {
    if (num % i === 0) return false;
  }
  return true;
}

@example
用于提供一个或多个函数调用的示例。

/**
 * 计算两数的平均值
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两个数的平均值
 * @example
 * // 返回 4
 * average(2, 6);
 */
function average(a, b) {
  return (a + b) / 2;
}

@deprecated
标记一个方法、属性或函数已被废弃，不推荐使用。

/**
 * @deprecated
 * 该方法已被弃用，请使用新的 `newMethod` 代替。
 */
function oldMethod() {
  // ...
}

@throws 或 @exception
用于描述函数可能抛出的异常。

/**
 * 将一个字符串转换为数字
 * @param {string} str - 要转换的字符串
 * @returns {number} 转换后的数字
 * @throws {Error} 如果输入不是有效的数字
 */
function parseNumber(str) {
  const num = parseFloat(str);
  if (isNaN(num)) {
    throw new Error("无效的数字格式");
  }
  return num;
}

注释函数的完整示例

/**
 * 计算一个数组的平均值
 * 
 * @param {number[]} arr - 一个包含数字的数组
 * @returns {number} 返回数组的平均值
 * @throws {Error} 如果数组为空，抛出错误
 * 
 * @example
 * // 返回 5
 * calculateAverage([3, 5, 7])
 */
function calculateAverage(arr) {
  if (arr.length === 0) {
    throw new Error('数组不能为空');
  }
  
  const sum = arr.reduce((total, num) => total + num, 0);
  return sum / arr.length;
}

注释类和对象

对于类和对象，我们也可以使用 JSDoc 来提供更详细的描述。

类的注释

/**
 * 表示一个矩形
 * 
 * @class
 */
class Rectangle {
  /**
   * 创建一个矩形
   * 
   * @param {number} width - 矩形的宽度
   * @param {number} height - 矩形的高度
   */
  constructor(width, height) {
    this.width = width;
    this.height = height;
  }

  /**
   * 计算矩形的面积
   * @returns {number} 返回矩形的面积
   */
  getArea() {
    return this.width * this.height;
  }
}