简介
在前端开发过程中，我们经常需要生成文档以方便他人或自己查看代码，这时候很有必要使用 jsdoc 工具对代码进行注释。然而，原始的 jsdoc 存在一些问题，可能会导致生成文档不符合我们的预期。那么，为了解决这些问题，jaguarjs-jsdoc-patched 应运而生。本文将为大家详细介绍这个 npm 包的使用方法以及注意事项。
安装
首先，我们需要在本地环境中安装 Node.js。安装 Node.js 可以参考 https://nodejs.org/zh-cn/，下载并安装对应的版本。
安装好 Node.js 之后，我们就可以使用 npm 命令来安装 jaguarjs-jsdoc-patched。在命令行中输入以下命令：
npm install jaguarjs-jsdoc-patched -g
其中，-g 表示全局安装。
使用
接下来，我们就可以使用 jaguarjs-jsdoc-patched 生成我们需要的文档了。在终端中切换到需要生成文档的目录，并依次执行以下命令：
# 初始化配置 jsdoc --configure node_modules/jaguarjs-jsdoc/jaguarjs.json # 生成文档 jsdoc -c jsdoc.json
注意，上述两行命令中的 jsdoc.json 是我们通过以下命令生成的配置文件：
jsdoc -d . -p -t node_modules/jaguarjs-jsdoc-patched/templates/default -c node_modules/jaguarjs-jsdoc-patched/conf.json node_modules/jaguarjs-jsdoc-patched/**/*.js
在执行完上述两条命令之后，我们就可以在当前目录下生成根据代码和注释生成的文档了。
注意事项
在使用 jaguarjs-jsdoc-patched 生成文档时，有一些需要注意的点：
- 为了保证生成的文档可以正确显示中文，需要在 jsdoc.json 中添加中文语言包路径：
-- -------------------- ---- ------- ------- - ----------- -------------------------------------------------------- ------------------ -------------- ------- ---------- ----- ---------- ----- ------------ -------------- --------------- -------------------------------------------------------- ------------ ------------------------------------------------ ----------- ------- --------- --------- -------- --- -------------- -------- ------- ------------------------------------------------------------------- ------------ ----------------------------------------------------------------------------- -展开代码
- 如果需要生成 API 接口文档，只需要将 API 相关的注释添加在文件顶部即可。
-- -------------------- ---- ------- --- - ---- ----- --------- ------- ---- ----------- - -------- ------- - --------- ---- - - --------- -------- -- ----- ------ --- - - ----------- -------- --------- --------- -- --- ----- - ----------- -------- -------- -------- -- --- ----- --展开代码
示例代码
-- -------------------- ---- ------- --- - ---- ----- - - ------ ---- -- ----- ---- - --- - ------ - ---- - - ------ -------- -- --- ---- -- - ------ -------- ---- --- ---- ---- - - -------- ------ --- --- ---- ------ -- --------------- ----- - ------- - --- --------- - ----- - --- - --- --- ---- -- - - -------- -------- --- ---- -- -- ------- - ------ -------- - --- - --- --- ---- ---- - - ------ -------- ---- --- ---- ---- - - -------- ----------- -- ------------- - --------- - ----- - --- - --- --- ---- ---- - - -------- -------- --- ---- ---- -- --------- - ------ ---------- - -展开代码
-- -------------------- ---- ------- - ---- ---- ----- -- ----- -- -------- - ------------- - ------ -- ----------------------------- - --------------------------- - ------------------- - ----------- - --------------- - ------------------- - ------------------- - ------------------------------- - ----------------------- -- ----------- --- ------ ------------ ---------- ----- ---- - --- -------- ------ ---------- - ------ ---------- - --- ---- -- - -------- ---------- - --- ---- ---- ---------- - -------- --- --- ---- ------- -- ------- --- ---- ----- -------- --- ---- -- --- ------ ----- -------- --- ---- ---- -- ------- --- --------- --- --- ---- -- ---------- ------------- ---------- - ---------- --- ---- -- --- --------------- --- --- ---- ---- ---------- ------------------- ---------- - -------- ---------- - --- ---- ---- --- ----------- --- --- ---- ---- ---------- --------------- ---------- - ---------- --- ---- ----展开代码
结语
通过本篇文章的介绍，我们知道如何使用 jaguarjs-jsdoc-patched 生成我们需要的文档。同时，我们也能够掌握如何处理遇到的一些问题。希望本文对于前端开发者能够提供参考和帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedb5bfb5cbfe1ea061146d
