轻松掌控 JSDoc：为你的 TypeScript 代码赋能

## TypeScript 自学课（3）- JSDoc 标记类型

TypeScript 作为一种强类型语言，需要在编译时明确变量的类型，以避免潜在的错误。然而，JavaScript 是一种弱类型语言，直到运行时才确定变量类型。为了弥合这一差距，JSDoc 应运而生。它是一种文档注释系统，允许你为 JavaScript 代码添加类型信息。

JSDoc 的类型注释

JSDoc 标记使用 /** 和 */ 符号包围，它们包含有关函数、参数和返回值的信息。

函数类型注释

/**
 * @param {string} name 用户名
 * @returns {boolean} 是否有效
 */
function validateName(name) {
  // ...
}

参数类型注释

/**
 * @param {number} x 第一个数字
 * @param {number} y 第二个数字
 * @returns {number} 两数之和
 */
function addNumbers(x, y) {
  return x + y;
}

返回值类型注释

/**
 * @returns {Promise<string>} 用户名
 */
async function getUsername() {
  // ...
}

JSDoc 标记类型

JSDoc 提供了多种类型标记来表示不同类型的数据：

• {number}：数字
• {string}：字符串
• {boolean}：布尔值
• {null}：null 值
• {undefined}：undefined 值
• {any}：任意类型（不检查类型）
• {void}：无返回值（对于没有返回值的函数）

联合类型和数组类型

JSDoc 还支持联合类型和数组类型：

联合类型

/**
 * @param {string|number} value 字符串或数字
 */
function handleValue(value) {
  // ...
}

数组类型

/**
 * @param {number[]} numbers 数组元素均为数字
 */
function sumArray(numbers) {
  // ...
}

使用 JSDoc 标记类型的优势

添加 JSDoc 类型注释的好处不胜枚举：

• 提高代码可读性 ：注释提供了清晰的类型信息，有助于快速理解代码的目的和功能。
• 增强可维护性 ：类型检查有助于及早发现错误，减少维护成本。
• 提升可重用性 ：明确的类型定义使得代码更容易被重用，减少冗余和错误。

结论

JSDoc 类型注释是提升 TypeScript 代码质量的宝贵工具。通过添加类型信息，你可以提高代码的可读性、可维护性和可重用性。充分利用 JSDoc 的功能，让你的 TypeScript 代码更强大。

---