前言
在前端开发中，我们常常需要将我们的代码文档化以方便增强代码可读性、可维护性以及未来代码的迭代。在Javascript领域，一个良好的工具就是Esdosc - 一个用于生成Javascript文档的工具。
在本文中，我们将介绍一个用于esdoc插件的npm包esdoc2-integrate-manual-plugin。该插件为Esdosc增强了手写文档的能力，使我们可以在一个文件夹下仅仅通过文本编辑器创建Markdown文件快速地创建、编写和保存文档。该插件依赖于esdoc 1.0.0及以上版本。
安装
我们可以通过npm安装该插件：
$ npm install esdoc2-integrate-manual-plugin
配置
为了启用该插件，我们需要在esdoc.json配置文件中的plugins属性添加该插件：
{
"source": "./src",
"destination": "./docs",
"plugins": [
{"name": "esdoc2-integrate-manual-plugin"}
]
}此外，我们还需要在json文件配置手写文档文件夹的路径：
-- -------------------- ---- -------
-
--------- --------
-------------- ---------
---------- -
-
------- ---------------------------------
--------- -
--------- -
------- ---------------
-
-
-
-
-使用
当我们配置好esdoc.json后，就可以创建新的markdown文档。在手写文档文件夹下创建新的markdown文件，如下命名：
/{namespace}/{name}.md其中，namespace是命名空间（$符号形式不能用），name是该Markdown文档的名称（必须拼接在路径的最后一位）。例如：
./docs/manual/MyESDocLibrary/Overview.md
在这个Markdown文件中，我们可以按照我们的喜好编写ESDoc，在我们的源代码中进行任何其他应用程序修建。
现在我们运行了esdoc命令，手写文档也出现在文档HTML文件的侧边栏中。
$ esdoc
示例代码
-- -------------------- ---- -------
---
- ------ -----
--
----- ------ -
---
- ----------- ------
- ------ --------- ---- - --- ------ -- ---- -- --- ------
--
----------- ------ -
--------- - -----
-
---
- ---- ------ - ---------- --- ---- -- --- ------
- -------- --------- --- ---- -- --- ------
--
---- -- -
------ --------- - ----------
-
-
---
- ------ -----
--
----- ------ -
---
- ----------- ------
- ------ --------- ------ - --- ------ -- --- ------
--
------------------- -
----------- - -------
-
---
- -------- - ---- ------ - ---------- --- ---- -- --- ------
- -------- --------- --- ---- -- --- ------
--
------ -
------ ------- - ----------- - ------------
-
-以上是一个简单的面向对象的代码片段，我们可以为它添加文档注释并通过esdoc2-integrate-manual-plugin插件手写markdown文档作为此静态HTML文档中的一部分。
结论
Esdosc是JavaScript开发的一个非常有用的文档工具，esdoc2-integrate-manual-plugin插件增强了手写文档的能力，使我们可以以自己最喜欢的方式创建快速的文档。在该插件的帮助下，我们可以快速地为代码添加文档，并提高可维护性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056c5481e8991b448e5d62