在前端开发过程中，编写文档是一个非常重要的工作。好的文档可以帮助团队成员更快地理解和使用代码，也可以帮助新手快速上手。但是，编写文档需要投入大量的时间和精力，如果没有好的工具辅助，往往会比较痛苦。而 npm 包 markdown-documentation 就是这样一款工具，可以帮助我们更轻松地编写文档。本篇文章主要介绍如何使用该 npm 包。
安装
首先，我们需要安装 markdown-documentation。使用 npm 命令安装即可：
--- ------- ---------------------- ----------
使用
接下来，我们就可以开始使用 markdown-documentation 了。markdown-documentation 包含两个核心功能：
- 自动生成 API 文档。
- 自动生成 README 文档。
自动生成 API 文档
我们可以使用 markdown-documentation 自动生成 API 文档。这需要我们在代码中使用特定的注释格式来标识 API，然后运行 markdown-documentation 工具生成文档。注释格式如下：
--- - --------- ------------ - ------------ -------- ----------- - ------ ------ --------- - ----- ----------- - -------- ------ ------ ----------- -- -------- ----------------------- - -- -------- ---- -
这样，我们就定义了一个名为 functionName 的函数，并加入了注释。其中 @function 表示这是一个函数，@description 表示函数描述，@param 表示函数参数，@returns 表示函数返回值。
在代码中添加好注释后，我们可以使用如下命令来生成 API 文档：
--- ---------------------- ------- ----- -------- -----------
其中，--input 表示输入的目录，这里我们输入的是 ./src，即代码所在的目录。--output 表示输出的文件，这里我们输出到 docs/api.md。
自动生成 README 文档
markdown-documentation 还可以自动生成 README 文档。我们只需要在项目的根目录下创建一个名为 README.md.ejs 的文件，然后在文件中使用 EJS 模板语言编写文档即可。
下面是一个简单的示例：
- -- ------- --- ----------- -- -- ------------ ------- --- ------- ---------- ------
Usage
----- --------- - --------------------- ----------------------
API
<%= getApi('api.md') %>
---------------- ----------------------------------- --------------- --- --- ----------------- ------ ----
npx markdown-documentation --readme ./README.md.ejs --output README.md
-- ---------- --------------- ---------------------------- --------------- ------------ -- -- ---------------------- ------------------- ---------------------------------- --- --- ------ ------------------------------------- ------------------------------------------------------------------------------ ---------- -----------------------------------------------------------------------------------------------------------------------------