JSDoc 注释规范：检查文本格式和详细注释

作为一名开发人员，编写清晰、易于理解的代码非常重要。JSDoc 是一种广泛用于 JavaScript 代码的文档生成工具，它允许你使用注释来生成 API 文档，从而使你的代码更易于理解和维护。本文将重点介绍 JSDoc 注释的文本格式和详细注释规范，帮助你写出更易于理解和维护的代码。

JSDoc 注释规范

1. 文本格式

使用单引号 (') 而不是双引号 (') 来包含字符串。
使用 Markdown 语法来格式化注释内容，例如：
- 使用 * 表示列表项
- 使用 # 表示标题
- 使用 ** 表示粗体
- 使用 _ 表示斜体

2. 详细注释

每个函数或方法都应该包含一个详细的 JSDoc 注释，包括：
- @param: 描述每个参数，包括类型和含义。
- @returns: 描述返回值的类型和含义。
- @throws: 描述函数可能抛出的错误，包括错误类型和含义。
- @example: 提供示例代码，展示函数的使用方法。

3. 代码示例

/**
 * 计算两个数字的和
 *
 * @param {number} a 第一个数字
 * @param {number} b 第二个数字
 * @returns {number} 两个数字的和
 * @throws {Error} 如果参数不是数字，则抛出错误
 * @example
 * add(1, 2); // 返回 3
 */
const add = (a, b) => {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('参数必须是数字');
  }
  return a + b;
};

工具和资源

JSDoc: https://jsdoc.app/
ESLint: https://eslint.org/
Markdown: https://www.markdownguide.org/

遵循这些规范可以确保你的 JSDoc 注释清晰易懂，并生成高质量的 API 文档，帮助你和其他开发人员更好地理解和维护你的代码。