JavaScript 方法 注释 完整版示例

目录

1.有参数示例

2.无参数示例

3.对象数组参数示例

4.含 注释目标的数据类型 和 特别声明 示例

---

1.有参数示例

// === 用户管理 模块方法 开始 ===

/**
 * @typedef {String} CityName
 * @enum {'A City' | 'B City' | 'C City'}
 */
 
/**
 * 根据城市设置程序里的一些本地配置信息（无返回值）。
 * @param {CityName} city - 城市名称
 * @param {String | Number | Boolean | Array | Object | Date | Function | Symbol | 任何自定义构造函数} otherParams - 其它参数，本参数只是为了展示语法和一些类型可选值而设置。
 * @returns {void}
 */
function setLocalInfo(city,otherParams) {
  // 方法实现
}

/**
 * 按条件过滤、排序和分页获取商品列表。
 *
 * @param {Object} options - 选项对象
 * @param {String[]} options.filters - 过滤器数组
 *                                    可选值: ['red', 'blue', 'green']
 * @param {String} options.sortBy - 排序字段
 *                                  可选值: 'price', 'name', 'rating'
 * @param {String} [options.sortOrder='asc'] - 排序顺序
 *                                             可选值:
 *                                                 - 'asc'：    顺序排序
 *                                                 - 'desc'：    倒序排序
 * @param {Number} [options.page=1] - 当前页码
 * @param {Number} [options.pageSize=10] - 每页显示数量
 * @returns {Object[]} 商品列表
 *
 * @example
 * // 使用示例1：按颜色过滤并按价格降序排序
 * const filters1 = ['red'];
 * const sortBy1 = 'price';
 * const sortOrder1 = 'desc';
 * const page1 = 2;
 * const pageSize1 = 20;
 * const products1 = getFilteredProducts({
 *   filters: filters1,
 *   sortBy: sortBy1,
 *   sortOrder: sortOrder1,
 *   page: page1,
 *   pageSize: pageSize1
 * });
 * console.log(products1);
 *
 * @example
 * // 使用示例2：按名称和评级过滤并使用默认排序和分页设置
 * const filters2 = ['name:XYZ', 'rating:5'];
 * const products2 = getFilteredProducts({
 *   filters: filters2
 * });
 * console.log(products2);
 */
function getFilteredProducts(options) {
  // 方法实现
}

// === 用户管理 模块方法 结束 ===

2.无参数示例

根据JSDoc注释约定，@param标签用于描述方法的参数。在没有参数的情况下，可以完全省略@param标签。
示例：

/**
 * 执行某个操作。
 */
function performAction() {
  // 方法实现
}

然而，如果认为在没有参数的方法中使用@param标签能够提供更清晰的文档或与其他方法保持一致的风格，也可以在注释中添加一个空的@param标签。
示例：

/**
 * 执行某个操作。
 * @param {} - 无参数
 */
function performAction() {
  // 方法实现
}

3.对象数组参数示例

/**
 * 处理对象数组数据。
 * @param {Array}  data - 包含对象的数组
 * @param {string} data[].name - 对象的名称
 * @param {number} data[].age - 对象的年龄
 * @returns {number} - 年龄总和
 */
function processData(data) {
  // 方法实现。
}

4.含 注释目标的数据类型 和 特别声明 示例

/**
 * @function calculateSum - Calculate the sum
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} - The sum of the two numbers.
 * @special Consider edge cases when either parameter is zero.
 */
function calculateSum(a, b) {
	return a + b;
}

说明：本文档内容是自行整理chatGPT相关问题回答内容 后 完成的。