用 JSDoc @typedef 和 @property 描述对象参数

2024-03-06 13:07:38

使用 JSDoc 对象参数

作为一名经验丰富的程序员和技术作家，我经常需要在文档和代码中 JavaScript 对象参数的结构。在本文中，我将分享如何使用 JSDoc @typedef 和 @property 注解来有效地描述对象参数。

理解 JSDoc

JSDoc 是一个开源注释工具，用于为 JavaScript 代码生成文档。通过在注释中使用特定的语法，我们可以指定类型、描述参数和返回值，以及记录其他相关信息。

使用 `@typedef` 定义对象类型

@typedef 注释用于定义一个新的类型，例如对象类型。它接受一个类型名称作为参数，并跟随一个花括号内的对象结构。例如：

/**
 * @typedef {object} Point
 * @property {number} x The x-coordinate.
 * @property {number} y The y-coordinate.
 */

上述注释定义了一个名为 Point 的对象类型，它具有两个属性：x 和 y，都是数字类型。

使用 `@property` 描述对象属性

@property 注释用于描述对象类型的属性。它接受两个参数：属性名称和一个描述对象，其中包含属性的类型、描述和可选选项。例如：

/**
 * @typedef {object} Options
 * @property {boolean} [enabled=true] Whether the feature is enabled.
 * @property {number} [timeout=1000] The timeout in milliseconds.
 */

上述注释定义了一个名为 Options 的对象类型，它有两个属性：

enabled：类型为布尔值，默认为 true
timeout：类型为数字，默认为 1000

[enabled=true] 语法表示 enabled 属性是可选的，默认为 true。

在参数注释中使用对象类型

一旦我们定义了一个对象类型，就可以在函数或方法的参数注释中使用它。例如：

/**
 * Creates a new point.
 *
 * @param {Point} point The point to create.
 */
function createPoint(point) {
  // ...
}

上述注释指定 createPoint 函数的参数 point 的类型为 Point 对象类型。

其他示例

以下是一些其他示例，说明如何使用 @typedef 和 @property 注解：

/**
 * @typedef {object} Employee
 * @property {string} name The employee's name.
 * @property {string} email The employee's email address.
 * @property {number} age The employee's age.
 */

/**
 * Gets the employee's name.
 *
 * @param {Employee} employee The employee object.
 * @returns {string} The employee's name.
 */
function getEmployeeName(employee) {
  return employee.name;
}

/**
 * @typedef {object} Configuration
 * @property {string} host The hostname or IP address of the server.
 * @property {number} port The port number to connect to.
 * @property {object} [headers={}] The HTTP headers to send with the request.
 */

/**
 * Sends a request to the server.
 *
 * @param {Configuration} config The configuration object.
 */
function sendRequest(config) {
  // ...
}