在进行代码开发的过程中，文档编写是不可缺少的一部分。而利用 jsdoc 描述文档可以让我们更自然地编写文档。jsdoc 的优点是可以针对函数，方法和属性编写注释，并生成 API 文档。但是通过 jsdoc 描述文档，我们仍然需要有一定的技术背景来编写出清晰的文档，如何使用插件来方便我们的文档编写呢？这里介绍一下 npm 包 jsdoc-plugins 的使用教程。
环境配置
首先，你需要在本地环境中配置好 Node.js 和 npm，这里不再赘述安装步骤。
接着，通过 npm 全局安装 jsdoc：
npm install -g jsdoc
同时，我们还需要安装 jsdoc-plugins，这样才能使用该插件功能：
npm install -g jsdoc-plugins
好了，现在，我们假设你已经写好了你的 JavaScript 代码，并需要从这些代码中生成文档。接下来，让我们看一下如何使用 jsdoc-plugins。
jsdoc-plugins 的使用
在上一节中，我们已经完成了 jsdoc-plugins 的安装。现在我们有一个非常简单的例子需要我们生成相关的 API 文档：
-- -------------------- ---- ------- --- - ------ --- ------ -- -- - -------- - --------- -- -------- - - -------- ------ - ------ -- -- - --------- ------ - ------ -------- ------ - --- ------ -- ------- - -------- -------- --- ------ -- --- --------- -- -------- -------------- - ------ ------ - -- -
对于上述代码，通过 jsdoc 执行命令 jsdoc my-script.js 可以生成 API 文档，但是我们需要在代码中加入相关的标记，以保证文档的正确生成。那么，我们就可以使用 jsdoc-plugins 来利用该插件在不更改代码的情况下来生成文档。
首先，在当前的项目目录下创建配置文件，命名为 jsdoc.conf.json ，并在该配置文件中加入以下代码：
-- -------------------- ---- -------
-
---------- -
------------------
--
----------- -
--------- ------
----------- ----
-
-其中，plugins/markdown 注册了 jsdoc-markdown 插件。你也可以在 "markdown" 属性中进一步细化你的配置需求。
接着，在写好 API 文档相关.js 文件后，我们使用 jsdoc 执行命令：
jsdoc myfile.js -r -t node_modules/jsdoc-template-cleanslate
其中，-r 表示执行递归搜索，将生成所有文件的文档；-t 表示使用 jsdoc 的清空板块清洁式输出。这样，我们就可以在当前项目目录下的 /out 目录中生成 HTML 格式的 API 文档了。
总结
上述步骤简单易懂地介绍了如何通过 jsdoc-plugins 实现方便的文档编写。与手动书写 Markdown 文件不同，jsdoc-plugins 并不需要额外写 Markdown 文件，使用起来也很方便。相信 jsdoc-plugins 可以大大简化我们编写文档的复杂度，提高编写效率。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5efef268403f2923b035bc00