【自动化】使用jsdoc实现自动生成文档

通过jsdoc将代码中的函数、方法、类和变量的注释语法文档化，并生成相应的 API 文档

相关文章

使用jsdoc实现自动生成文档

一、JS Doc 是什么

JSDoc 是一种用于 JavaScript 代码文档化的标准和工具。它允许开发人员通过特定的注释语法将代码中的函数、方法、类和变量文档化，并生成相应的 API 文档。

二、JS Doc 的好处

生成文档： JSDoc 注释允许开发者在代码中添加文档注释，描述函数、类、方法等的作用、参数、返回值等信息。通过使用 JSDoc 工具，可以根据这些注释自动生成详细的代码文档，使得代码的使用和维护更加方便。
提高代码可读性： JSDoc 注释使得代码更加易读，可以清晰地了解函数、类、方法的功能和用法，有助于降低代码的维护成本。
提供代码提示： JSDoc 注释可以与一些编辑器和 IDE 结合使用，例如 Visual Studio Code、WebStorm 等，这些编辑器可以根据 JSDoc 注释提供代码提示、自动完成等功能，帮助开发者更高效地编写代码。
增强团队协作：通过添加详细的 JSDoc 注释，可以帮助团队成员更好地理解代码，减少沟通成本，提高团队协作效率。
规范代码风格：使用 JSDoc 注释可以规范代码注释的格式和内容，使得整个项目的代码风格更加统一，易于阅读和维护。

三、基本用法

文档化函数和方法

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

文档化类

/**
 * 表示一个人的类
 * @class
 */
class Person {
  /**
   * 创建一个人的实例
   * @param {string} name - 人的名字
   * @param {number} age - 人的年龄
   */
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }

  /**
   * 获取人的名字
   * @returns {string} 人的名字
   */
  getName() {
    return this.name;
  }
}

四、常用标记

@param

指定函数或方法的参数及其类型。

@returns

指定函数或方法的返回值及其类型。

@class

标识一个类。

@constructor

标识类的构造函数。

@property

文档化类的属性。

@throws 或 @exception

文档化函数可能抛出的异常。

五、生成文档

安装并使用 JSDoc 工具，可以根据代码中的 JSDoc 注释生成 API 文档。例如，在命令行中执行 jsdoc yourfile.js 即可生成相应的 API 文档。

实际工作中，可能会执行批量生成或者条件生成；则可以用如下方法

命令行调用：在命令行中使用 JSDoc 的命令，并指定需要生成文档的文件或目录。例如：

1	`jsdoc path/to/your/files/*.js`

配置文件：创建一个 JSDoc 的配置文件（通常命名为 jsdoc.conf.json），在配置文件中指定需要生成文档的文件或目录以及其他配置选项。然后通过命令行调用 JSDoc，并指定配置文件。例如

1	`jsdoc -c jsdoc.conf.json`

脚本调用：创建一个 Node.js 脚本，使用 JSDoc 的 API 调用来动态地生成文档。例如

const jsdoc = require('jsdoc-api');

// 设置 JSDoc 配置
const options = {
  files: 'path/to/your/files/*.js',
  // 其他配置选项...
};

// 生成文档
jsdoc.explain(options).then(documentation => {
  console.log(documentation);
}).catch(error => {
  console.error(error);
});

更多用户请参考 JS Doc 官网

六、文档预览

七、重写默认模板的布局文件

默认的模板使用名为 layout.tmpl 的文件指定每个生成文档的页面中的页眉和页脚。特别是，每个生产的文档页面会加载该文件定义了 CSS 和 JavaScript 文件。在 JSDoc3.3.0 或更高版本，可以指定使用自己的 layout.tmpl 文件，它允许你加载自己的自定义 CSS 和JavaScript 文件，去除或替代，标准的文件。

要使用此功能，设置选项 templates.default.layoutFile 的路径到你的自定义布局文件。路径是相对于 config.json 文件，当前的工作目录，和 JSDoc 目录的相对路径，按照这个顺序。

喜欢这篇文章？打赏一下支持一下作者吧！