JSDoc使用 JSDoc 记录你的 JavaScript 代码

介绍

安装

用法

关于 JSDoc 的其他精彩内容

介绍

在这篇文章中，我将尽量涵盖 JSDoc 入门所需的一切知识。我还会分享一些我学到的其他一些有趣的知识，希望对您有所帮助。

目录

• 安装
• 用法
  • 文档
  • 出口
  • 导出文件或文件夹
  • 递归导出所有文件
  • 使用配置文件
• 关于 JSDoc 的其他精彩内容
  • VSCode 内置支持
  • 使用自定义布局
  • JSDoc 和 Swagger
  • 知道其他有趣的 JSDoc 功能吗？

JSDoc是一个开源的 JavaScript API 文档生成器。它允许开发者通过注释来记录他们的代码。以下是一个例子：

/**
 *  Retrieves a single file by id.
 *  @param {string} id File identifier.
 *  @returns {File} File object.
 */
const getFileById = (id) => {
    // ...
}

一旦你的代码文档齐全，你只需运行一个简单的命令，就能轻松生成一个包含所有 API 文档的网站。是不是很酷？

上面的代码在生成的网站中看起来是这样的：

安装

使用以下命令通过npm全局安装 JSDoc ：

npm install -g jsdoc

或者使用以下命令为单个项目安装它：

npm install --save-dev jsdoc

有关安装的更多信息请点击此处

说实话，虽然我很久以前就用 JSDoc 注释来记录我的代码，但直到几周前我才安装这个包，因为我实际上并不需要生成网站。我只是把它和 VSCode 一起使用，不过我会在本文后面讨论这个问题。

用法

文档

要开始记录您的代码，您所要做的就是在/**您想要记录的每个代码块上添加以 开头的注释：模块、方法、类、函数等。

您只需添加描述即可使其变得简单：

/**
 * Retrieves a user by email.
 */
const getByEmail = async (email) => {
    // ...
}

或者您可以使用标签充分利用 JSDoc：

/**
 * Retrieves a user by email.
 * @async
 * @method
 * @param {String} email - User email
 * @returns {User} User object
 * @throws {NotFoundError} When the user is not found.
 */
const getByEmail = async (email) => {
    // ...
}

您可以从大量的标签列表中进行选择，以便尽可能详细地记录您的代码。

请记住，注释中的信息越多，API 文档就越详细。但也要找到适合自己的详细程度。最好只用几个标签来记录所有代码，而不是只用所有标签来完整记录几个方法，因为那样会太多，你无法跟上进度。

出口

添加评论后，剩下要做的就是生成您的文档网站：

导出文件或文件夹

只需调用 jsdoc 并添加文件或文件夹的路径。

jsdoc path/to/my/file.js

要包含多个文件或文件夹，请添加所有路径并用一个空格分隔。

递归导出所有文件

jsdoc -r .

使用配置文件

您可能正在处理一个大型项目，其中包含许多需要导出的文件和文件夹，同时还有一些需要排除的文件和文件夹（我正在关注您，node_modules）。如果是这种情况，您可能需要使用 JSDoc 配置文件。

使用配置文件允许我们自定义 JSDoc 行为，例如：

• 应包括哪些文件夹或文件以及应排除哪些文件夹或文件。
• 当我们使用该选项时，JSDoc 将会深入到什么程度--recurse。
• 将自定义内容应用于模板
• ETC

您需要做的就是创建一个.json包含所需设置的文件，然后使用-c或--configure选项告诉 JSDoc 它们在哪里：

jsdoc -c /path/to/conf.json

下面是一个我经常使用的（非常简单的）例子：

{
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",   // Only process file ending in .js, .jsdoc or .jsx
        "include": ["."],                       // Check all folders.
        "exclude": ["node_modules"]             // Be gone, node_modules.
    },
    "recurseDepth": 10,                         // Only go 10 levels deep.
    "opts": {
        "destination": "./docs/",               // Where I want my docs to be generated.
        "recurse": true                         // Same as using -r or --recurse
    }
}

专业提示：
您可能需要将命令添加到您的 package.json 脚本中：

"scripts": {
    "generate-docs": "jsdoc -c /path/to/my/conf.js"
}

然后只需npm run generate-docs从命令行使用即可。

或者你可以为脚本使用更愚蠢的名称，例如：docs-pls，gimme-docs或者ill-have-the-large-docs-with-extra-docs（好吧，也许不是最后一个😅）。

有关配置的更多信息请点击此处

关于 JSDoc 的其他精彩内容

VSCode 内置支持

所以，就像我说的，我在安装 JSDoc 之前就很喜欢它，这是因为 VSCode 内置了对 JSDoc 注释的支持，其中包括：

• /**当您在函数声明前键入（然后按回车键）时，为您构建 JSDoc 注释结构的代码片段。
• 丰富的悬停信息
• 有关您正在使用的函数签名的信息

有关 VSCode 中 JSDoc 支持的更多信息，请查看VSCode 文档。

使用自定义布局

您可以通过生成自定义layout.tmpl文件并在 JSDoc 配置文件中将选项设置templates.default.layoutFile为自定义布局的路径来为您的 API 文档创建自己的模板。

没时间自己生成模板？这里有一些非常简洁的模板项目供您参考：

• 南
• DocStrap
• Braintree JSDoc模板

JSDoc 和 Swagger

该项目swagger-jsdoc将 JSDoc 与 swagger 集成在一起，允许您使用块代码上的标签@swagger为路线编写规范：

  /**
   * @swagger
   * /:
   *   get:
   *     description: Returns all users.
   *     responses:
   *       200:
   *         description: All users were returned.
   */
  app.get('/users', (req, res) => {
    // ...
  });

知道其他有趣的 JSDoc 功能吗？

在评论区告诉我吧！👇