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中，编写 /** 后，智能感知会自动建议一个JSDoc注释，按下回车键，然后按照下面的示例编写注释。

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

运行步骤： 要运行jsdoc，打开终端并输入以下命令

npm run jsdoc

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

输出：