玩转微服务-技术篇-JSDOC教程

一. 简介

JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。

JSDoc 是一种用于 JavaScript 代码文档注释的标记语言和工具。它不仅仅是一种文档编写方式，更是一种代码规范和团队协作工具。通过使用 JSDoc 注释，开发人员可以将关于函数、类、方法、参数、返回值等方面的信息嵌入到代码中，从而帮助其他开发人员更轻松地理解和使用代码。

文档地址：中文文档地址

英文地址：英文文档地址

二. 文档注释的意义

编写JavaScript的文档注释有助于提高代码的可读性、生成易于阅读的API文档、明确接口规范、辅助调试和维护工作，以及促进团队合作和知识共享。这是为了更好地组织和记录代码，并使其更易于理解和使用的最佳实践之一。

• 提供代码的可读性：文档注释可以帮助其他开发人员更好地理解你的代码。通过提供清晰的注释，可以解释代码的目的、使用方法和重要细节，使代码更易于阅读和维护。

• 自动生成文档：许多开发工具和框架可以根据代码中的文档注释来自动生成文档。例如，JSDoc 是一个常用的JavaScript文档生成工具，它可以解析文档注释并生成API文档。这样其他开发人员就可以轻松地查看代码的接口和用法。

• 提供接口定义和规范：通过文档注释，可以明确说明函数、类、方法和参数的用途、类型和预期行为。这不仅帮助其他开发人员正确使用你的代码，还可以在团队协作中提供一致性和规范。

• 辅助代码调试和维护：当你在调试和维护代码时，文档注释可以提供有关代码功能和实现细节的重要信息。这对于理解复杂的功能和排查问题非常有帮助，尤其是当你需要处理他人编写的代码或长时间未接触的代码时。

• 促进团队合作和知识共享：文档注释可以为开发团队提供一个共享的知识库，使所有人都能理解代码的功能和实现细节。这有助于提高团队成员之间的沟通和协作，并促进代码质量和一致性。

三. 命令行参数

JSDoc 支持大量的命令行选项，其中许多选项有长和短两种形式。或者，JSDoc 命令行选项可以在配置文件中指定。命令行选项：

详细参见：https://jsdoc.bootcss.com/about-commandline.html

四. 配置说明

1. 配置文件的类型

自定义 JSDoc 的行为，可以使用以下格式之一向 JSDoc 提供配置文件：

• 一个JSON文件。在JSDoc 3.3.0及更高版本中，此文件可能包含注释。
• 导出单个配置对象的 CommonJS 模块。JSDoc 3.5.0及更高版本支持这种格式。

要使用配置文件运行 JSDoc，请使用 -c 命令行选项（例如，jsdoc -c /path/To/conf.json 或 jsdoc -c /path/To/conf.js）。

2. 默认配置说明

默认配置内容

{
  "plugins": [],
  "recurseDepth": 10,
  "source": {
    "include": [ /* array of paths to files to generate documentation for */ ],
    "exclude": [ /* array of paths to exclude */ ],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "sourceType": "module",
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  },
   "opts": {
    "template": "templates/default",  // same as -t templates/default
    "encoding": "utf8",               // same as -e utf8
    "destination": "./out/",          // same as -d ./out/
    "recurse": true,                  // same as -r
    "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
  }
}

• 无插件加载（plugins）;
• 如果使用 -r 命令行标志启用递归，JSDoc 将搜索 10 层深的文件（recurseDepth）；
• 只有以 .js、.jsdoc 和 .jsx 结尾的文件将会被处理（source.includePattern）；
• 任何文件以下划线开始或开始下划线的目录都将被忽略（source.excludePattern）；
  • source.include：可选的路径数组，JSDoc应该为它们生成文档。JSDoc 将会结合命令行上的路径和这些文件名，以形成文件组，并且扫描。如果路径是一个目录，可以使用 -r 选项来递归。
  • source.exclude：可选的路径数组，JSDoc 应该忽略的路径。在 JSDoc3.3.0 或更高版本，该数组可包括 source.include 路径中的子目录。
  • source.includePattern：一个可选的字符串，解释为一个正则表达式。如果存在，所有文件必须匹配这个正则表达式，以通过 JSDoc 进行扫描。默认情况下此选项设置为.+.js(doc)?$，这意味着只有以 .js、.jsdoc 和 .jsx 结尾的文件将被扫描。
  • source.excludePattern：一个可选的字符串，解释为一个正则表达式。如果存在的话，任何匹配这个正则表达式的文件将被忽略。默认设置是以下划线开头的文件（或以下划线开头的目录下的所有文件）将被忽略。
• JSDoc 支持使用 ES2015 modules（sourceType）；
• JSDoc 允许您使用无法识别的标签（tags.allowUnknownTags）,该属性影响 JSDoc 如何处理无法识别的标签。如果将此选项设置为 false，JSDoc发现它不能识别（例如,@foo），JSDoc 将记录一个警告。默认情况下，此选项设置为 true。；
• 标准 JSDoc 标签和 closure 标签被启用（tags.dictionaries）；
  • 属性控制 JSDoc 识别哪些标签，以及 JSDoc 如何解析它识别标签。在 JSDoc3.3.0 或更高版本中，有两个内置的标签词典：
    • jsdoc: 核心JSDoc标签
    • closure: Closure Compiler 标签
• @link标签呈现在纯文本（templates.cleverLinks，templates.monospaceLinks）。
• opt: 可以将 JSDoc 的许多命令行选项放入配置文件中，而不是在命令行中指定它们。为此，将相关选项的长名称添加到配置文件的 opts 部分，并将值设置为该选项的值。

五. 标签

JSDoc支持两种不同类型的标签：

• 块标签(Block), 这是在一个JSDoc注释的最高级别。
• 内联标签(inline), 块标签文本中的标签或说明。

块标签通常会提供有关您的代码的详细信息，如一个函数接受的参数。内联标签通常链接到文件的其他部分，类似于HTML中的锚标记（<a>）。

块标签总是以 at 符号（@）开头。除了 JSDoc 注释中最后一个块标记，每个块标签后面必须跟一个换行符。

内联标签也以 at 符号（@）开。然而，内联标签及其文本必须用花括号（{ and }）括起来。 { 表示行内联标签的开始，而 } 表示内联标签的结束。如果你的标签文本中包含右花括号（}），则必须用反斜线（ \ ）进行转义。在内联标签后,你并不需要使用一个换行符。

1. 块级标签

块级标签使用说明

2. 内联标签

内联标签使用说明

六. 使用

1. 安装：

npm install -g jsdoc

2. 生成文档

jsdoc -r src -d doc

-r表示源目录，-d表示生成的目标目录，或者使用配置文件生成：

jsdoc -c /path/to/conf.json