什么是 update-markdown-jsdoc?
update-markdown-jsdoc 是一个 npm 包，它可以将 jsdoc 注释转换为 markdown 文档，从而更好地记录和展示代码的文档。这个包适用于任何使用 jsdoc 注释并希望生成文档的项目。
安装
使用 npm 进行安装：
npm install update-markdown-jsdoc --save-dev
使用方法
首先，在你的 JavaScript 文件中添加 jsdoc 注释，例如：
-- -------------------- ---- ------- --- - ---- --- ------- --------- - ------ -------- ---- - --- ----- ------ -- ---- - ------ -------- ---- - --- ------ ------ -- ---- - -------- -------- - --- --- -- --- --- -------- -- -------- ---------------- ----- - ------ ---- - ----- -
然后，在命令行中运行以下命令：
update-markdown-jsdoc <input_path> <output_path>
其中 input_path 是输入文件路径，output_path 是输出文件路径。例如：
update-markdown-jsdoc src/index.js docs/README.md
这将会把 src/index.js 中的所有 jsdoc 注释转换为 markdown 格式，并且保存到 docs/README.md 中。
高级用法
模板
你可以使用模板来自定义文档的样式。在模板中，你可以使用任何合法的 markdown 和 jsdoc 模板标记。例如，以下是一个简单的模板：
-- -------------------- ---- ------- - --- -- -- --- ------ ---- -- ------ - -- -- --- --------- -- --- ---------------- -- --- - -- - -- - -- - - --- - --- - --- - -- --- ------ ----- -- ------------ - -- - --- ---------- -- - ---- ------------------------ -- --- - --- ----------------- -- - -- - -- -------- ---------------------------------- -- --- - --- --------------------------- -- -- - --
在命令行中，加上 --template <template_file_path> 参数来指定模板文件路径。例如：
update-markdown-jsdoc src/index.js docs/README.md --template docs/template.md
过滤器
你可以使用过滤器来过滤掉某些 jsdoc 注释。在命令行中，加上 --filter <filter> 参数来指定过滤器。例如：
update-markdown-jsdoc src/index.js docs/README.md --filter private
这将会过滤掉所有带有 @private 标签的 jsdoc 注释。
示例代码
以下是一个完整的示例代码：
-- -------------------- ---- -------
---
- ---- --- ------- ---------
- ------ -------- ---- - --- ----- ------ -- ----
- ------ -------- ---- - --- ------ ------ -- ----
- -------- -------- - --- --- -- --- --- --------
--
-------- ---------------- ----- -
------ ---- - -----
-
---
- --------- --- --------
- ------ -------- ---- - --- ------ -- -------- -----
- ------ -------- ---- - --- ------ -- ---------
- -------- -------- - --- ---------- -- --- --- --------
--
-------- --------------------- ----- -
------ ---- - -----
-
---
- ---------- --- --------
- ------ -------- ---- - --- ----- ------ -- ---------
- ------ -------- ---- - --- ------ ------ -- ---------
- -------- -------- - --- ------- -- --- --- --------
--
-------- --------------------- ----- -
------ ---- - -----
-
---
- ------- --- --------
- ------ -------- ---- - --- ----------
- ------ -------- ---- - --- ------------
- -------- -------- - --- -------- -- --- --- --------
- ------- ---- ----- -- ----- -- ------ -- -----
--
-------- ------------------- ----- -
-- ----- --- -- -
----- --- ------------- ------ -- --------
- ----------------------------------------------------------- --------
----------------------------------------------------------------------------------