前言
docdash 是基于 JSDoc 格式的文档生成器。它的特点在于能够生成简约、干净的文档界面，同时也支持主题切换。这使得 docdash 受到了广泛的欢迎，被用于很多 popular 的 package 中，例如 React、Express、Angular 等。本文将会带领大家详细了解 docdash 的使用方法和其相关配置。
安装
为了安装 docdash 必须需要先安装 Node.js，而且 Node.js 的版本最好是在 v8.15.0 或以上。
npm install -g docdash
安装完成后，你需要将以下代码添加到 package.json 中：
"scripts": {
"doc": "jsdoc -c .jsdoc.json"
},其中，-c 选项用于加入一个指向配置文件的选项。该文件名后缀名必须为 .js，这里命名为 .jsdoc.json。
接下来，我们将会创建一个文件夹 docs，为它增加一些必要的文件。目录结构如下图所示：
docs/ |-- js/ | |-- common.js |-- swagger/ | |-- index.html |-- .jsdoc.json |-- index.html
js/ 里的 common.js 包含了例子，你可以根据实际情况修改和删减，swagger/index.html 则是你的 API 文档，而 index.html 则是启 动文档的首页。.jsdoc.json 文件是用于配置文档生成的一些参数，将在下面的章节中讲解。
配置
创建常用的 jsdoc.json 文件，配置如下所示：
-- -------------------- ---- -------
-
------- -
------------------- ----
--
--------- -
---------- ---------
---------- -
----------------
--
----------------- -----------------
----------------- ---------------
--
------- -
----------- -------------------------
-------------- ------------
---------- -----
---------- -----
--
---------- -
------------------
--
----------- -
--------- --------
-
-如上所述，我们使用了 docdash 的默认模板，并将其安装到了 ./node_modules/docdash 中。你的文档将会生成到 swagger 目录下，生成的文档不包括私有（@private）的方法。我们通过 “plug-ins” 字段来使用 Markdown 语法。
相信务必不少人会疑惑这里的 markdown 字段是什么意思。其实，他是用于说明结合 Markdown 解析器如何处理 markdown 文本。在这个示例中，我们可以使用 marked，当然像其它的优秀开源库一样，也可以使用 Markdown-it 等工具。
下面是常用配置选项，你可以根据你的项目需求进行选择：
-- -------------------- ---- -------
-
---------- -
------------------
--
------------------- -----
--------- -
----------------- -----------------
----------------- ---------------
--
------- -
----------- -------------------------
-------------- ------------
---------- -----
---------- -----
-
-例子
下面是一段例子:
-- -------------------- ---- ------- --- - ----------- - ---- ------ ---- --- --- ------- - - ------ -------- - - ----- -------- - ------ -------- - - ------ -------- - -------- -------- --- --- -- - --- - -- -------- ------ -- - ------ - - -- -
为了在最终文档中添加 Markdown，我们需要在 .jsdoc.json 文件中增加 markdown 中的 parser 值。示例如下：
-- -------------------- ---- -------
-
------- -
------------------- ----
--
--------- -
---------- ---------
---------- -
----------------
--
----------------- -----------------
----------------- ---------------
--
------- -
----------- -------------------------
-------------- ------------
---------- -----
---------- -----
--
---------- -
------------------
--
----------- -
--------- --------
-
-现在，我们来为 add() 函数添加一些 Markdown。看下面的代码示例：
-- -------------------- ---- ------- --- - ----------- - ---- ------ ---- --- --- ------- - - ------ -------- - - ----- -------- - ------ -------- - - ------ -------- - -------- -------- --- --- -- - --- - - - -------- - - ----- - --- --- - ------ --- - ---------- -- --- - --- - - ---- ---------------------------------------------------------- -- -------- ------ -- - ------ - - -- -
上面的 add 函数定义了一个代码段。它能够实现 add 的测试。你能够使用代码块、引用和其他 Markdwon 语法来沉淀你的文档。
结论
在这篇文章中，我们详细介绍了如何使用 npm 包 docdash 来生成符合 JSDoc 格式的文档。我们说明了如何在项目中加入其相关配置和流程，还有列出了一些重要的示例代码。希望本文能对你的前端学习和开发有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60989