简介
jsdoc-md 是一款基于 jsdoc 的 npm 包，用于自动生成 API 文档，文档格式为 markdown。它适用于 JavaScript、TypeScript 和 JSX 函数库以及 React 组件的文档生成。通过使用 jsdoc-md，您可以方便地为您的 JavaScript 库快速生成漂亮的 API 文档。
安装
使用 npm 安装 jsdoc-md
npm install -g jsdoc-md
安装完成后，我们就可以在终端中使用 jsdoc-md 命令了。
使用教程
创建配置文件
在您的 JavaScript 库的根目录下创建一个 .jsdoc.json 文件，然后在里面写入以下内容：
-- -------------------- ---- -------
-
--------- -
---------- --------
----------------- -------------------
----------------- ---------------
--
---------- -
------------------
--
------- -
-------------- --------
---------- -----
----------- ------
-
-该文件配置了哪些文件需要包含进文档，使用哪些插件以及文档的生成路径等。
创建注释
jsdoc-md 单独使用时，最重要的部分是你在写程序中添加的注释。注释是生成 API 文档的基础。在注释中，您需要描述如何使用您的函数、参数和返回值的预期类型以及更多其他的有用信息。
注释标准采用 JSDoc 格式。下面是一个简单的例子：
-- -------------------- ---- ------- --- - ------- - - ------ -------- - - -- - ------ -------- - - -- - -------- -------- ------ -- -------- ------ -- - ------ - - -- -
生成文档
在终端中输入以下命令并回车，就可以自动生成 API 文档了：
jsdoc-md .jsdoc.json
这个命令将会在 docs/ 文件夹下面生成一个 api.md 文件，该文件中包含了您程序中的所有函数、参数和返回值的详细信息。
查看文档
在您的浏览器中打开 api.md 即可查看文档。
高级用法
配置使用主题
jsdoc-md 支持使用多种主题，您可以根据需要自由选择。在配置文件中添加以下内容就可以更改主题了：
-- -------------------- ---- -------
-
------------ -
------------- -
------------- --------------------------------
-------------- -
------ -
---------------------------
-
-
-
--
------- -
----------- ------------
-
-使用其它插件
jsdoc-md 支持多个插件，您可以自由选择添加使用。
{
"plugins": [
"plugins/markdown",
"/path/to/your/plugin.js"
]
}配置 tags
jsdoc-md 默认提供了较完整的 JSDoc Tags 支持，但您也可以按照自己需求添加或者修改标记。在配置文件中添加以下内容就可以添加自定义标记：
-- -------------------- ---- -------
-
------------ -
------------- -
------------- --------------------------------
-------------- -
------ -
---------------------------
-
-
-
--
------- -
----------- -------------
------- -
------------ -
------- ------------
------------ ------
------------- ----------------
----------- ------------
------- -------
-------------- -------------
-
-
-
-总结
通过学习本文，您已经学会了如何使用 jsdoc-md 自动生成漂亮的 API 文档。不仅如此，您还学会了如何自定义配置文件和如何高效运用 jsdoc-md。您可以根据您的需求为您的 JavaScript 库创建专业的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/72708