JavaScript内核与高级编程之：`JavaScript`的`JSDoc`：如何利用注释进行类型标注和文档生成。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

嘿！各位观众老爷们，欢迎来到今天的JavaScript奇妙夜！我是你们的老朋友，Bug终结者，今天咱们要聊点儿高大上的玩意儿——JSDoc。别怕，听名字唬人，其实就是让你的代码穿上西装，打上领带，显得更专业，更有条理！说白了，就是好好写注释，但写出点儿花样来。

JSDoc：注释中的战斗机

JSDoc，全称JavaScript Documentation，是一个用于从JavaScript源代码中生成API文档的工具。简单来说，就是你按照一定的格式写注释，然后JSDoc工具就能帮你自动生成漂亮的文档。这玩意儿就像是给你的代码写了一本说明书，让别人（也包括未来的你）更容易理解和使用你的代码。

为什么要用JSDoc？

提高代码可读性： 好的注释能解释代码的功能、参数和返回值，让代码更容易理解。
自动生成文档： 告别手动编写文档的痛苦，JSDoc帮你自动生成，省时省力。
类型检查： JSDoc可以进行类型标注，配合TypeScript等工具，可以进行静态类型检查，减少运行时错误。
团队协作： 规范的注释风格，方便团队成员理解和维护代码。

JSDoc的基本语法

JSDoc的注释以/**开始，以*/结束，中间可以包含各种标签（tags），用于描述代码的各个方面。

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

常用JSDoc标签

标签	描述	示例
`@param`	描述函数的参数。	`@param {string} name 用户的姓名。`
`@returns`	描述函数的返回值。	`@returns {number} 计算结果。`
`@type`	描述变量或属性的类型。	`@type {string}`
`@typedef`	定义一个自定义类型。	`@typedef {Object} User 用户对象。 @property {string} name 用户的姓名。 @property {number} age 用户的年龄。`
`@property`	描述对象的属性。	`@property {string} email 用户的邮箱。`
`@class`	描述一个类。	`@class Person 人类。`
`@constructor`	描述类的构造函数。	`@constructor`
`@method`	描述一个类的方法。	`@method sayHello 打招呼。`
`@private`	标记一个成员为私有。	`@private`
`@public`	标记一个成员为公共。	`@public`
`@protected`	标记一个成员为受保护的。	`@protected`
`@deprecated`	标记一个成员为已弃用。	`@deprecated 使用新的方法代替。`
`@author`	描述作者。	`@author 张三`
`@version`	描述版本号。	`@version 1.0.0`
`@since`	描述从哪个版本开始引入。	`@since 1.0.0`
`@see`	引用其他相关的代码或文档。	`@see {@link add}`
`@example`	提供代码示例。	`javascript add(1, 2); // 3`
`@fires`	描述函数触发的事件。	`@fires User#event:login`
`@listens`	描述函数监听的事件。	`@listens User#event:logout`
`@ignore`	忽略该代码块，不生成文档。	`@ignore`
`@async`	标记函数为异步函数。	`@async`
`@await`	描述异步函数中等待的结果。	`@await fetch('https://example.com')`

类型标注

JSDoc最强大的功能之一就是类型标注。你可以使用@type、@param、@returns等标签来指定变量、参数和返回值的类型。

/**
 * 计算圆的面积。
 *
 * @param {number} radius 圆的半径。
 * @returns {number} 圆的面积。
 */
function calculateArea(radius) {
  return Math.PI * radius * radius;
}

复杂类型

对于复杂类型，可以使用对象、数组、联合类型等。

/**
 * @typedef {Object} Point
 * @property {number} x X坐标。
 * @property {number} y Y坐标。
 */

/**
 * 计算两点之间的距离。
 *
 * @param {Point} p1 第一个点。
 * @param {Point} p2 第二个点。
 * @returns {number} 两点之间的距离。
 */
function calculateDistance(p1, p2) {
  const dx = p1.x - p2.x;
  const dy = p1.y - p2.y;
  return Math.sqrt(dx * dx + dy * dy);
}

联合类型

可以使用|来表示联合类型，表示变量可以是多种类型之一。

/**
 * 打印消息。
 *
 * @param {string | number} message 要打印的消息，可以是字符串或数字。
 */
function printMessage(message) {
  console.log(message);
}

数组类型

可以使用Array<type>或type[]来表示数组类型。

/**
 * 计算数组中所有数字的和。
 *
 * @param {Array<number>} numbers 数字数组。
 * @returns {number} 数组中所有数字的和。
 */
function sum(numbers) {
  let total = 0;
  for (const number of numbers) {
    total += number;
  }
  return total;
}

/**
 * 计算数组中所有数字的和 (另一种写法).
 *
 * @param {number[]} numbers 数字数组.
 * @returns {number} 数组中所有数字的和.
 */
 function sum2(numbers) {
    let total = 0;
    for (const number of numbers) {
      total += number;
    }
    return total;
  }

对象类型

可以使用Object或自定义typedef来表示对象类型。

/**
 * @typedef {Object} User
 * @property {string} name 用户的姓名。
 * @property {number} age 用户的年龄。
 */

/**
 * 打印用户信息。
 *
 * @param {User} user 用户对象。
 */
function printUserInfo(user) {
  console.log(`姓名：${user.name}，年龄：${user.age}`);
}

函数类型

可以使用Function来表示函数类型，也可以使用更详细的函数类型定义。

/**
 * @typedef {function(number, number): number} MathOperation
 */

/**
 * 执行数学运算。
 *
 * @param {number} a 第一个数字。
 * @param {number} b 第二个数字。
 * @param {MathOperation} operation 数学运算函数。
 * @returns {number} 运算结果。
 */
function calculate(a, b, operation) {
  return operation(a, b);
}

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

// 使用示例
const result = calculate(1, 2, add); // 3

泛型

JSDoc也支持泛型，可以使用@template标签来定义泛型类型。

/**
 * @template T
 * @param {T[]} array
 * @returns {T}
 */
function first(array) {
  return array[0];
}

类和构造函数

可以使用@class和@constructor标签来描述类和构造函数。

/**
 * @class Person
 * @classdesc 表示一个人类。
 */
class Person {
  /**
   * @constructor
   * @param {string} name 姓名。
   * @param {number} age 年龄。
   */
  constructor(name, age) {
    /**
     * @private
     * @type {string}
     */
    this.name = name;
    /**
     * @private
     * @type {number}
     */
    this.age = age;
  }

  /**
   * 打招呼。
   *
   * @returns {string} 问候语。
   */
  sayHello() {
    return `你好，我是${this.name}，今年${this.age}岁。`;
  }
}

事件

可以使用@fires和@listens标签来描述事件。

/**
 * @class User
 * @fires User#event:login
 * @fires User#event:logout
 */
class User {
  /**
   * 登录。
   */
  login() {
    /**
     * 用户登录事件。
     * @event User#event:login
     * @type {object}
     * @property {string} username 用户名。
     */
    this.emit('login', { username: this.username });
  }

  /**
   * 退出登录。
   */
  logout() {
    /**
     * 用户退出登录事件。
     * @event User#event:logout
     */
    this.emit('logout');
  }
}

生成文档

有多种工具可以用来生成JSDoc文档，其中最常用的是JSDoc Toolkit。

安装JSDoc Toolkit：
```
npm install -g jsdoc
```
生成文档：
```
jsdoc your-javascript-file.js
```
或者，如果你想生成整个项目的文档：
```
jsdoc .
```
JSDoc Toolkit会生成一个out目录，里面包含了你的文档。

JSDoc的进阶用法

配置JSDoc： 可以通过配置文件来定制JSDoc的行为，例如指定模板、包含的文件、排除的文件等。
使用插件： JSDoc有很多插件可以扩展其功能，例如支持Markdown、UML等。
与TypeScript集成： JSDoc可以与TypeScript集成，利用TypeScript的类型检查功能，提高代码质量。

最佳实践

保持注释的简洁性： 注释应该简洁明了，避免冗余信息。
及时更新注释： 当代码发生变化时，及时更新注释，保持注释与代码的一致性。
使用一致的风格： 团队应该统一JSDoc的风格，保持代码的一致性。
不要过度注释： 不要为显而易见的代码添加注释，注释应该解释代码的意图和逻辑。

代码示例：一个完整的例子

/**
 * @module MyModule
 */

/**
 * 这是一个用于处理用户信息的模块。
 */
const MyModule = {
  /**
   * @typedef {Object} User
   * @property {string} id 用户的ID。
   * @property {string} name 用户的姓名。
   * @property {number} age 用户的年龄。
   * @property {string} email 用户的邮箱。
   */

  /**
   * 获取用户信息。
   *
   * @param {string} id 用户的ID。
   * @returns {Promise<User>} 用户信息。
   * @throws {Error} 如果用户不存在。
   * @async
   * @example
   * ```javascript
   * MyModule.getUser('123')
   *   .then(user => console.log(user))
   *   .catch(err => console.error(err));
   * ```
   */
  async getUser(id) {
    // 模拟从数据库获取用户信息
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        const user = {
          id: id,
          name: '张三',
          age: 30,
          email: '[email protected]'
        };
        if (user) {
          resolve(user);
        } else {
          reject(new Error('用户不存在'));
        }
      }, 1000);
    });
  },

  /**
   * 更新用户信息。
   *
   * @param {string} id 用户的ID。
   * @param {Object} data 要更新的数据。
   * @param {string} [data.name] 用户的姓名。
   * @param {number} [data.age] 用户的年龄。
   * @param {string} [data.email] 用户的邮箱。
   * @returns {Promise<User>} 更新后的用户信息。
   * @async
   */
  async updateUser(id, data) {
    // 模拟更新数据库中的用户信息
    return new Promise((resolve) => {
      setTimeout(() => {
        const updatedUser = {
          id: id,
          name: data.name || '李四', // 默认值
          age: data.age || 25,
          email: data.email || '[email protected]'
        };
        resolve(updatedUser);
      }, 500);
    });
  }
};

export default MyModule;

总结

JSDoc是一个强大的工具，可以帮助你编写更清晰、更易于维护的JavaScript代码。通过合理地使用JSDoc标签，你可以为你的代码添加丰富的类型信息和文档，提高代码的可读性和可维护性，方便团队协作，减少错误。

希望今天的讲解对大家有所帮助！记住，好的代码不仅要能运行，还要能让人看懂！下次再见！

发表回复 取消回复

发表回复取消回复