js 文档注释

在 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;}
}