js封装公共方法注释规范

在 JavaScript 中进行方法封装时，注释是良好文档和可读性的重要组成部分。以下是一些建议的 JavaScript 方法封装注释规范：

/**
 * @function
 * @description 计算两个数字的和
 * @param {number} num1 - 第一个数字
 * @param {number} num2 - 第二个数字
 * @returns {number} - 两个数字的和
 * @throws {Error} - 当输入不是数字时抛出错误
 * @example
 * const result = addNumbers(2, 3);
 * console.log(result); // 输出: 5
 * @see {@link https://example.com} - 相关文档链接
 * @author Jam 
 */
function addNumbers(num1, num2) {
  if (typeof num1 !== 'number' || typeof num2 !== 'number') {
    throw new Error('Both parameters must be numbers');
  }
  return num1 + num2;
}

1. @function: 标识注释块是一个函数。
2. @description: 提供对函数作用的简要描述。
3. @param {type} paramName - description: 描述函数参数，包括参数的类型、名称和描述。
4. @returns {type} - description: 描述函数的返回值类型和描述。
5. @throws {type} - description: 描述函数可能抛出的异常或错误。
6. @example: 提供示例用法。
7. @see: 提供相关文档或链接。
8. @see: 编写此方法的作者。

在 JSDoc 中，有许多标签可用于对函数进行注释。这只是列举了一些常用的，其余没有一一列举

具体参考官方文档：Use JSDoc: Index