JavaScript内核与高级编程之：`JavaScript` 的 `JSDoc`：如何利用 `JSDoc` 对 `JavaScript` 代码进行类型标注。

各位观众老爷们，大家好！今天咱们不聊风花雪月，只聊代码界的“身份证”—— JSDoc！没错，就是那个能让你的 JavaScript 代码瞬间变得“高贵”起来的注释神器。

开场白：谁还没个“类型焦虑症”？

话说，JavaScript 这门语言，天生自带“奔放”属性。它允许你随意定义变量，随意赋值，就像一个没怎么管教过的孩子，自由自在，无拘无束。但这自由过了头，也容易出问题。比如，你定义了一个变量叫 age，本来是想存年龄的，结果一不小心塞了个字符串进去，程序跑起来就可能给你整出幺蛾子。

这种“类型不确定性”，让很多程序员都患上了“类型焦虑症”。他们渴望一种方式，能给 JavaScript 代码加上类型信息，让代码更健壮，更易于维护，也更方便团队协作。

于是乎，JSDoc 就应运而生了！

JSDoc 是什么？能吃吗？

JSDoc，全称 JavaScript Documentation，是一种基于注释的文档生成工具。它允许你在 JavaScript 代码中添加特定格式的注释，然后通过工具（比如 JSDoc 本身，或者 VS Code 等 IDE 的内置支持）解析这些注释，生成漂亮的 API 文档。

但 JSDoc 的作用远不止于生成文档。更重要的是，它可以用来为 JavaScript 代码添加类型标注，让你的代码拥有“类型信息”，从而获得更好的代码提示、类型检查和重构支持。

你可以把 JSDoc 想象成是给 JavaScript 代码颁发的“身份证”。有了身份证，别人就知道你是谁，有什么特征，该怎么对待你。

JSDoc 的基本语法：像写段子一样简单

JSDoc 的注释以 /** 开头，以 */ 结尾。注释内容由一系列的“标签”（tag）组成，每个标签都以 @ 符号开头。

比如，下面是一个简单的 JSDoc 注释的例子：

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

在这个例子中，我们使用了 @param 标签来描述函数的参数，使用 @returns 标签来描述函数的返回值。{number} 表示参数和返回值的类型都是数字。

是不是感觉像在写段子？只需要用 @ 符号加上一些描述性的文字，就能给你的代码添加类型信息。

常用的 JSDoc 标签：十八般武艺样样精通

JSDoc 提供了丰富的标签，可以用来描述各种类型的代码元素。下面是一些常用的标签：

标签	描述	示例
@param	描述函数的参数。	/** @param {string} name 姓名。*/
@returns	描述函数的返回值。	/** @returns {number} 年龄。*/
@type	描述变量的类型。	/** @type {string} */ var name = "张三";
@typedef	定义一个自定义类型。	javascript /** * @typedef {object} Person * @property {string} name - 姓名。 * @property {number} age - 年龄。 */
@property	描述对象的一个属性。	javascript /** * @typedef {object} Person * @property {string} name - 姓名。 * @property {number} age - 年龄。 */ var person = { name: "张三", age: 18 };
@class	描述一个类。	javascript /** * @class * @classdesc 描述一个动物类。 */ class Animal { constructor(name) { this.name = name; } }
@constructor	描述一个构造函数。 用于老的构造函数写法	javascript /** * @constructor * @param {string} name 姓名。 */ function Person(name) { this.name = name; }
@extends	描述一个类继承自另一个类。	javascript /** * @class * @extends Animal * @classdesc 描述一个狗类，继承自动物类。 */ class Dog extends Animal { constructor(name, breed) { super(name); this.breed = breed; } }
@private	标记一个成员为私有成员。	javascript /** @private */ var secret = "这是一个秘密";
@public	标记一个成员为公共成员。	javascript /** @public */ var name = "张三";
@protected	标记一个成员为受保护成员。	javascript /** @protected */ var age = 18;
@deprecated	标记一个成员为已弃用。	javascript /** @deprecated 请使用新的方法。*/ function oldMethod() { // ... }
@callback	描述一个回调函数。	javascript /** * @callback RequestCallback * @param {string} responseData - 请求的响应数据。 * @param {number} statusCode - 请求的状态码。 */ /** * 发起一个请求。 * @param {string} url - 请求的 URL。 * @param {RequestCallback} callback - 请求完成后的回调函数。 */ function request(url, callback) { // ... }
@interface	描述一个接口。	javascript /** * @interface */ class Animal { eat() {} sleep() {} }
@enum	描述一个枚举类型。	javascript /** * @enum {string} */ const Color = { RED: 'red', GREEN: 'green', BLUE: 'blue' };
@constant	描述一个常量。	javascript /** @constant */ const PI = 3.1415926;
@async	标记一个函数为异步函数。	javascript /** @async */ async function fetchData() { // ... }
@generator	标记一个函数为生成器函数。	javascript /** @generator */ function* generateNumbers() { yield 1; yield 2; yield 3; }
@yields	描述生成器函数的每次 yield 的值。	javascript /** * @generator * @yields {number} 生成的数字。 */ function* generateNumbers() { yield 1; yield 2; yield 3; }
@fires	描述函数触发的事件。	javascript /** * @fires MyComponent#event:dataLoaded */ MyComponent.prototype.loadData = function() { /** * Data loaded event. * * @event MyComponent#event:dataLoaded * @type {object} * @property {object} data - The loaded data. */ this.emit('dataLoaded', { data: this.data }); };
@listens	描述函数监听的事件。	javascript /** * @listens MyComponent#event:dataLoaded */ MyComponent.prototype.onDataLoaded = function(event) { console.log('Data loaded:', event.data); };

这些标签就像十八般武艺，你可以根据不同的场景选择合适的标签来描述你的代码。

JSDoc 的类型系统：五花八门，应有尽有

JSDoc 支持多种类型，包括：

• 基本类型： number、string、boolean、null、undefined、symbol、bigint
• 对象类型： object、{}
• 数组类型： Array、number[]、string[]
• 函数类型： function、(number, string) => boolean
• 自定义类型： 使用 @typedef 标签定义的类型
• 联合类型： number | string
• 泛型： Array<number>

这些类型就像各种口味的冰淇淋，你可以根据自己的喜好选择合适的类型来描述你的代码。

JSDoc 的实战演练：让代码“亮”起来

光说不练假把式，下面我们通过几个例子来演示如何使用 JSDoc 对 JavaScript 代码进行类型标注。

例子 1：给函数添加类型标注

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

在这个例子中，我们使用了 @param 标签来描述函数的参数 a 和 b，指定它们的类型为 number。我们还使用了 @returns 标签来描述函数的返回值，指定它的类型也为 number。

例子 2：给变量添加类型标注

/** @type {string} */
var name = "张三";

/** @type {number} */
var age = 18;

/** @type {boolean} */
var isMale = true;

在这个例子中，我们使用了 @type 标签来描述变量 name、age 和 isMale 的类型，分别是 string、number 和 boolean。

例子 3：定义一个自定义类型

/**
 * @typedef {object} Person
 * @property {string} name - 姓名。
 * @property {number} age - 年龄。
 */

/**
 * 创建一个 Person 对象。
 *
 * @param {string} name 姓名。
 * @param {number} age 年龄。
 * @returns {Person} 一个 Person 对象。
 */
function createPerson(name, age) {
  return {
    name: name,
    age: age
  };
}

在这个例子中，我们使用了 @typedef 标签来定义一个自定义类型 Person，它是一个包含 name 和 age 属性的对象。我们还使用了 @property 标签来描述 Person 类型的属性，指定它们的类型和描述。

JSDoc 的最佳实践：让代码更上一层楼

• 保持注释的简洁性： 注释应该简洁明了，避免冗余和重复。
• 使用一致的风格： 团队应该统一 JSDoc 的风格，保持代码的一致性。
• 及时更新注释： 当代码发生变化时，应该及时更新注释，保持注释的准确性。
• 使用工具进行验证： 可以使用 JSDoc 工具或者 IDE 的内置支持来验证 JSDoc 注释的正确性。
• 不要过度注释： 不要为了注释而注释，只注释那些需要解释的代码。

JSDoc 的未来展望：拥抱 TypeScript

虽然 JSDoc 可以为 JavaScript 代码添加类型信息，但它毕竟只是一种注释，无法提供真正的类型检查。随着 TypeScript 的流行，越来越多的 JavaScript 项目开始采用 TypeScript 来进行类型标注。

TypeScript 是一种强类型的 JavaScript 超集，它提供了更强大的类型检查和代码提示功能。如果你对类型安全有更高的要求，可以考虑使用 TypeScript。

当然，即使你使用了 TypeScript，JSDoc 仍然有用武之地。你可以使用 JSDoc 来生成 API 文档，或者为那些无法迁移到 TypeScript 的 JavaScript 代码添加类型标注。

总结：JSDoc，你的代码“身份证”！

JSDoc 是一种强大的工具，可以用来为 JavaScript 代码添加类型标注，生成 API 文档，提高代码的可读性、可维护性和可重用性。

虽然它不能完全替代 TypeScript，但在某些场景下仍然是一种非常有用的选择。

所以，赶紧给你的 JavaScript 代码办个“身份证”吧！让它们也变得“高贵”起来！

好了，今天的讲座就到这里。感谢大家的收听！希望大家能学到一些有用的知识，并在实际工作中灵活运用。再见！