JSDoc简介

在代码库中包含文档有其广泛的好处，其中一些好处包括易于新程序员和想要重新访问他们过去的代码库的高级程序员理解代码，在记录代码时，您需要正确地总结它，这最终会有所帮助适当地理解整个代码库。

JSDoc – JavaScript 的 API 文档生成器。

JSDoc 是 Javascript 的文档生成器，它类似于 JavaDoc 或Python Docstrings。您需要在代码中包含文档注释，然后 JSDoc 将在这些注释的帮助下生成一个 HTML 文档网站。

安装JSDoc的步骤

要全局安装 JSDoc，请运行以下命令

npm install -g jsdoc

如果您需要在项目中安装 JSDoc 作为开发依赖项，请改为运行此命令

npm install -D jsdoc

配置 JSDoc

在package.json 的“scripts”属性中，我们需要添加 jsdoc 命令来运行 JSDoc 并生成文档，在package.json文件中添加类似于下面给出的命令

"scripts": {
    "jsdoc": "jsdoc -c jsdoc.json"
    ...
  }

该命令有一个-c标签，表示 jsdoc 将使用自定义配置文件运行，因此让我们为 JSDoc 创建一个配置文件。

在项目目录的根目录中创建一个名为“jsdoc.json”的文件，在该文件中添加以下代码：

Javascript

{
  "plugins": ["plugins/markdown"],
  "recurseDepth": 10,
  "source": {
    "include": ["src"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "opts": {
    "destination": "./jsdoc",
    "recurse": true,
    "readme": "./readme.md"
  }
}

解释：

• 启用了 Markdown 插件，可将 Markdown 格式的文本转换为 HTML
• recurseDepth 值设置为10，表示jsdoc将搜索文件的深度有多少级
• 为了指定输入，我们在include属性中包含了“src”，这意味着 jsdoc 将为 src 目录中的文件生成文档
• 包含模式捐赠要选择的文件，这里.js$表示它将包含.js、.jsx和.jsdoc文件
• 不包括 Node_modules 和 docs 文件夹
• 模板决定生成文档的外观
• opts 部分包括 JSDoc 命令

运行 JSDoc

让我们在 src 文件夹中创建一个文件 index.js 并在其中声明一个变量以生成文档

Javascript

/**
 * Site Name
 * @type {string}
 */
const siteName = "GeeksForGeeks";

这里我们创建了一个名为“siteName”的字符串，在注释中，我们有一个简单的变量描述和@type标签，它表示变量的类型
在 VSCode 中写入/**后，IntelliSense 会自动建议一个 JSDoc 注释，按回车键，然后写入如下所示的注释。

现在我们的代码已准备好文档，让我们运行 jsdoc 并创建一个文档

运行步骤：要运行 jsdoc，请打开终端并编写以下命令

npm run jsdoc

这个命令会在你的项目目录的根目录下创建一个“ jsdoc ”文件夹，在里面会生成一个 index.html 文件，你可以在浏览器中打开它来查看我们生成的文档

输出：

生成的 HTML 文档