jsdoc

JavaScript是一门动态类型的语言，虽然它具备高度灵活性，但也有着代码可读性低、缺乏类型约束的缺点。JSDoc是一种用于在JavaScript代码中生成文档的工具，它通过在代码中添加注释元信息来描述函数、类或变量，起到对类型约束等信息辅助说明的目的，这篇笔记我们介绍JSDoc的注释语法和基本使用方法。

JSDoc注释语法

这里我们介绍JSDoc的基本语法和最佳实践。

标注变量

下面例子中，我们使用JSDoc注释标注了一个变量，约束str变量为字符串类型。

/** @type {string} */
const str = "Hello, world!";

代码中，如果你对str赋值为非字符串类型，代码仍能正常运行，但如果使用支持JSDoc的IDE编辑代码，通常IDE会给出警告信息。

JSDoc的@type注释中，除了基本类型，我们也可以使用复杂类型或是指定多个类型。

/** @type {Pos} */
const pos = new Pos();

/** @type{str|number} */
let a;

此外，我们也可以添加一些除类型外的文字说明信息。

/**
 * 数字例子
 * @type {number}
 */
const num = 1;

标注函数

JSDoc注释可以标注函数的说明信息、参数类型和返回值，下面是一个例子。

/**
 * 例子函数
 * @param x {number} 加数
 * @param y {number} 被加数
 * @returns {number} 返回值
 */
function demo(x, y) {
    return x + y;
}

标注类和方法

JSDoc还可以标注类、类成员和方法的参数和返回值，下面是一个例子。

/**
 * 向量
 */
class Vector {
    /**
     * x坐标
     * @type {number}
     */
    x;

    /**
     * y坐标
     * @type {number}
     */
    y;

    /**
     * 构造函数
     * @param x {number} x坐标
     * @param y {number} y坐标
     */
    constructor(x, y) {
        this.x = x;
        this.y = y;
    }

    /**
     * 计算向量长度
     * @returns {number} 向量长度
     */
    length() {
        return Math.sqrt(this.x * this.x + this.y * this.y);
    }
}

JSDoc工具使用

我们可以使用npm命令全局安装JSDoc工具。

npm install -g jsdoc

使用JSDoc工具很简单，我们直接在包含源码的目录下运行jsdoc命令行工具即可。

jsdoc .

此外，如果只希望针对某个文件生成文档，可以使用类似jsdoc demo.js的写法。

默认情况下，相关的文档会以HTML形式输出到当前文件夹的out目录下，我们可以打开其中的index.html查看文档。