JSDoc 注释规范：提升代码可读性与类型提示

好的，各位代码界的英雄豪杰，大家好！我是你们的老朋友，BUG克星，代码美容师，今天咱们来聊聊一个能让你的代码瞬间颜值飙升，还能让合作者对你刮目相看的神奇工具：JSDoc 注释规范！

先别打哈欠，我知道，注释嘛，听起来就像课堂上老师念叨的“要好好写作业”，让人昏昏欲睡。但请相信我，JSDoc 可不是那种让你头疼的作业，它更像是一把魔法棒，能让你的代码变得清晰易懂，自带说明书，还能帮你提前发现潜在的 BUG，简直就是代码界的“美颜相机”+“体检中心”！

一、 为什么你的代码需要 JSDoc？（故事的开始）

想象一下，你写了一段精妙绝伦的代码，宛如一首优雅的诗，代码运行得飞起，功能强大到爆炸。你兴奋地把代码交给你的同事小明，让他来维护或者扩展一下。

三天后，小明一脸懵逼地找到你：“老大，这段代码……我看了半天，愣是没看懂！这变量名起的，简直就是摩斯密码！还有，这个函数到底是干嘛的？输入是什么？输出是什么？完全是薛定谔的猫啊，不运行一下谁也不知道！”

你听了，心里咯噔一下，心想：“完了，我写的代码只有我自己能看懂，这不就成了代码界的孤芳自赏了吗？”

这就是我们为什么要使用 JSDoc 的原因！它就像一本详细的说明书，告诉别人（也包括未来的你）：

• 这段代码是干嘛的？ （功能描述）
• 它需要什么？ （输入参数及类型）
• 它会返回什么？ （返回值类型）
• 有没有什么坑？ （异常情况、注意事项）

有了 JSDoc，小明再也不用对着你的代码抓耳挠腮了，他可以快速了解代码的功能，轻松上手维护和扩展。你的代码也从“代码界的孤芳自赏”变成了“代码界的万人迷”，人人争相阅读，啧啧称赞。

二、 JSDoc 是什么？（揭开面纱）

JSDoc 是一种用于为 JavaScript 代码生成 API 文档的标记语言。简单来说，它就是一种特殊的注释格式，你可以用它来描述你的代码，然后使用 JSDoc 工具将这些注释转换成漂亮的 HTML 文档。

你可以把 JSDoc 想象成一个专业的“代码翻译官”，它能把你的代码翻译成易于理解的语言，让任何人都能轻松读懂你的代码。

三、 JSDoc 的基本语法（掌握魔法）

JSDoc 注释以 /** 开始，以 */ 结束。每一行注释都以 * 开头。

/**
 * 这是一个简单的函数，用于计算两个数字的和。
 *
 * @param {number} a 第一个数字。
 * @param {number} b 第二个数字。
 * @returns {number} 两个数字的和。
 */
function add(a, b) {
  return a + b;
}

在这个例子中，/** ... */ 就是 JSDoc 注释。@param 和 @returns 是 JSDoc 标签，它们用于描述函数的参数和返回值。

四、 JSDoc 常用标签（施展魔法）

JSDoc 有很多标签，每个标签都有不同的作用。下面是一些常用的标签：

标签	描述	示例
@param	描述函数的参数。	javascript /** * @param {string} name 用户的名字。 * @param {number} age 用户的年龄。 */ function greet(name, age) { console.log(`你好，${name}，你今年 ${age} 岁了！`); }
@returns	描述函数的返回值。	javascript /** * @returns {string} 欢迎消息。 */ function getGreeting() { return "欢迎来到我的网站！"; }
@type	描述变量的类型。	javascript /** * @type {string} */ let message = "Hello, world!";
@typedef	定义一个自定义类型。	javascript /** * @typedef {object} User * @property {string} name 用户的名字。 * @property {number} age 用户的年龄。 */ /** * @param {User} user 用户对象。 */ function displayUser(user) { console.log(`用户名：${user.name}，年龄：${user.age}`); }
@class	描述一个类。	javascript /** * @class Rectangle * @param {number} width 矩形的宽度。 * @param {number} height 矩形的高度。 */ class Rectangle { constructor(width, height) { this.width = width; this.height = height; } /** * 计算矩形的面积。 * @returns {number} 矩形的面积。 */ getArea() { return this.width * this.height; } }
@constructor	描述一个构造函数。与@class类似，但更明确地指出这是构造函数。	javascript /** * @constructor Person * @param {string} name 人的名字。 * @param {number} age 人的年龄。 */ function Person(name, age) { this.name = name; this.age = age; }
@property	描述对象的属性。	javascript /** * @typedef {object} Address * @property {string} street 街道地址。 * @property {string} city 城市。 */
@description 或 @desc	描述代码的功能。这个标签可以提供更详细的说明。	javascript /** * 计算圆的面积。 * @description 这个函数接受圆的半径作为参数，并返回圆的面积。 * @param {number} radius 圆的半径。 * @returns {number} 圆的面积。 */ function calculateCircleArea(radius) { return Math.PI * radius * radius; }
@author	描述代码的作者。	javascript /** * @author John Doe */ function doSomething() { // ... }
@deprecated	标记代码已过时，不建议使用。	javascript /** * @deprecated 这个函数已经过时，请使用 `newFunction` 代替。 */ function oldFunction() { // ... }
@example	提供代码的使用示例。	javascript /** * @example * // returns 5 * add(2, 3); */ function add(a, b) { return a + b; }
@fires 或 @emits	说明代码会触发哪些事件。	javascript /** * @fires User#event:login 当用户登录时触发。 */ function login(username, password) { // ... }
@listens	说明代码监听哪些事件。	javascript /** * @listens Document#event:keydown 监听键盘按下事件。 */ function handleKeyDown(event) { // ... }
@ignore	告诉 JSDoc 工具忽略这段代码。	javascript /** * @ignore 这个函数不应该出现在文档中。 */ function secretFunction() { // ... }
@license	说明代码的许可证。	javascript /** * @license MIT */ function doSomething() { // ... }
@link	创建一个链接到其他文档或代码的链接。	javascript /** * 更多信息请参考 {@link https://example.com/docs}。 */ function doSomething() { // ... }
@private	标记代码为私有，不应该在文档中公开。	javascript /** * @private 这个变量是私有的，不应该直接访问。 */ let _privateVariable = 123;
@public	标记代码为公共，可以在文档中公开。默认情况下，所有代码都是公共的，除非使用 @private 标记。	javascript /** * @public 这个函数是公共的，可以公开访问。 */ function publicFunction() { // ... }
@since	说明代码是在哪个版本中引入的。	javascript /** * @since 1.0.0 */ function doSomething() { // ... }
@throws	说明代码可能会抛出哪些异常。	javascript /** * @throws {Error} 如果输入无效，则抛出错误。 */ function validateInput(input) { if (!input) { throw new Error("输入无效！"); } }

注意： 以上只是一些常用的标签，JSDoc 还有很多其他的标签，你可以根据自己的需要选择使用。

五、 JSDoc 的最佳实践（成为大师）

• 保持注释的简洁明了： 注释应该简洁明了，避免冗长和复杂的描述。
• 使用正确的标签： 选择合适的标签来描述你的代码，确保信息的准确性。
• 保持注释的更新： 随着代码的修改，及时更新注释，保持注释与代码的一致性。
• 使用 JSDoc 工具生成文档： 使用 JSDoc 工具将你的注释转换成漂亮的 HTML 文档，方便其他人阅读。

六、 JSDoc 工具（如虎添翼）

有很多 JSDoc 工具可以帮助你生成 API 文档，例如：

• JSDoc： 官方的 JSDoc 工具，功能强大，使用广泛。
• Doxygen： 一个通用的文档生成工具，支持多种编程语言，包括 JavaScript。
• ESDoc： 一个专门为 ES2015+ 代码设计的文档生成工具。

这些工具可以自动扫描你的代码，提取 JSDoc 注释，并生成漂亮的 HTML 文档。你可以将这些文档发布到你的网站上，或者分享给你的同事，方便他们了解你的代码。

七、 举个栗子（实战演练）

假设我们要写一个函数，用于计算数组的平均值。我们可以这样写 JSDoc 注释：

/**
 * 计算数组的平均值。
 *
 * @param {number[]} arr 数字数组。
 * @returns {number} 数组的平均值。如果数组为空，则返回 0。
 * @throws {TypeError} 如果数组中包含非数字元素，则抛出类型错误。
 * @example
 * // returns 2.5
 * average([1, 2, 3, 4]);
 * @example
 * // returns 0
 * average([]);
 */
function average(arr) {
  if (!Array.isArray(arr)) {
    throw new TypeError("参数必须是一个数组！");
  }

  if (arr.length === 0) {
    return 0;
  }

  let sum = 0;
  for (let i = 0; i < arr.length; i++) {
    if (typeof arr[i] !== 'number') {
      throw new TypeError("数组中必须包含数字元素！");
    }
    sum += arr[i];
  }

  return sum / arr.length;
}

在这个例子中，我们使用了 @param、@returns、@throws 和 @example 标签来描述函数的参数、返回值、异常情况和使用示例。这样，任何人都可以快速了解这个函数的功能和用法。

八、 JSDoc 与 TypeScript（强强联合）

如果你正在使用 TypeScript，那么 JSDoc 就更加重要了。TypeScript 是一种静态类型的 JavaScript 超集，它可以帮助你提前发现代码中的类型错误。

但是，TypeScript 只能检查类型信息，而无法提供代码的功能描述和使用示例。这时，JSDoc 就可以派上用场了。

你可以使用 JSDoc 注释来补充 TypeScript 的类型信息，提供更完整的代码文档。例如：

/**
 * 计算两个数字的和。
 *
 * @param {number} a 第一个数字。
 * @param {number} b 第二个数字。
 * @returns {number} 两个数字的和。
 */
function add(a: number, b: number): number {
  return a + b;
}

在这个例子中，我们使用了 TypeScript 的类型注解来声明参数和返回值的类型，同时使用 JSDoc 注释来描述函数的功能。这样，我们既可以享受 TypeScript 的类型检查带来的好处，又可以拥有 JSDoc 的代码文档功能。

九、 总结（代码界的“美容秘籍”）

JSDoc 注释规范就像代码界的“美容秘籍”，它能让你的代码变得清晰易懂，自带说明书，还能帮你提前发现潜在的 BUG。掌握 JSDoc，你就能写出高质量的代码，成为代码界的“万人迷”。

所以，各位英雄豪杰，不要再犹豫了，赶紧拿起你的键盘，开始为你的代码“美容”吧！相信我，你会爱上 JSDoc 的！ 😉

希望这篇文章能帮助你更好地理解 JSDoc 注释规范。如果你有任何问题，欢迎随时提问！祝你编程愉快！🎉