介绍
jsdoc-to-markdown 是一个 npm 包，可以将 JavaScript 文件中的 JSDoc 注释转换为 Markdown 格式的文档。它是一款非常有用的工具，可以帮助开发人员自动生成代码文档，并且让代码的阅读和理解更加方便。
安装
在开始使用 jsdoc-to-markdown 之前，需要先安装它。可以通过以下命令在项目中安装：
npm install -g jsdoc-to-markdown
使用
安装完成后，就可以使用 jsdoc-to-markdown 命令来生成 Markdown 文档了。下面是一个简单的例子，假设你有一个叫做 example.js 的文件：
-- -------------------- ---- ------- --- - -------- - - ------ -------- - ----- - ------ -------- - ----- - -------- -------- ------ -- -------- ------ -- - ------ - - -- -展开代码
现在，运行以下命令：
jsdoc2md example.js
输出如下：
-- -------------------- ---- ------- - ------ -- -------- --------- ------ -------- - ----- - ---- - ----------- - - --- - --- - --- - - - - ------------------- - ----- - - - - ------------------- - ----- - ------------ ------------------- - ------展开代码
可以看到，jsdoc-to-markdown 已经将 JSDoc 注释转换成了 Markdown 格式的文档。使用这种方式生成文档非常方便，而且可以大幅度减少手写文档的时间和工作量。
高级用法
除了上面介绍的基本用法之外，jsdoc-to-markdown 还支持许多高级用法，例如：
使用配置文件
可以使用 jsdoc-to-markdown 的配置文件来指定一些选项，例如要忽略哪些文件、使用哪个模板等等。在项目根目录创建一个名为 jsdoc2md.json 的文件，并设置选项即可。例如：
{ "files": [ "src/**/*.js", "!src/test/*.js", "!src/**/*-test.js" ], "template": "doc.ejs" }
自定义模板
默认情况下，jsdoc-to-markdown 使用的是自带的模板，但是你也可以使用自己编写的模板来生成文档。只需要在配置文件中设置 template 选项即可。
结合 Gulp 等构建工具使用
如果你使用 Gulp 或其他构建工具来构建项目，那么可以使用 gulp-jsdoc-to-markdown 这个插件来集成 jsdoc-to-markdown。具体使用方法可以参考插件的官方文档。
总结
通过本文的介绍，相信读者已经了解了 npm 包 jsdoc-to-markdown 的基本使用方法。当然，这只是 jsdoc-to-markdown 的冰山一角，它还有非常多的高级用法和选项。如果你想深入学习，可以查看官方文档了解更多内容。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/42214
