在前端开发中，注释是非常重要的一部分。注释既可以用来解释代码的含义，也可以用来生成文档，方便团队协作。而 jsdoc-rtd 就是一个能够将注释转换为漂亮文档的 npm 包。下面就详细介绍 jsdoc-rtd 的使用方法。
安装
在终端执行以下命令安装 jsdoc-rtd：
npm install -g jsdoc-rtd
配置
在项目根目录下创建一个 .jsdoc.json 文件。在该文件中配置 jsdoc-rtd 的参数。例如：
-- -------------------- ---- -------
-
--------- -
---------- ---------
--
------- -
-------------- ---------
----------- ----------------------------------
---------- ----
-
-其中 "source" 参数指定源代码所在文件夹，"opts" 参数指定文档生成的目标文件夹，模板文件夹以及是否递归。
编写注释
在每个函数或变量上方写注释，格式为：
/**
* 函数或变量的作用
* @param {参数类型} 参数名 描述
* @returns {返回值类型} 返回值描述
*/示例代码：
-- -------------------- ---- ------- --- - ------- - ------ -------- - ---- - ------ -------- - ---- - -------- -------- ----- -- -------- ------ -- - ------ - - -- -
可以看到，注释中包括了函数作用，参数及其类型以及返回值及其类型。
生成文档
在终端中执行以下命令生成文档：
jsdoc2md ./src/* > ./docs/index.md
其中，./src/* 指定源文件的路径，./docs/index.md 是生成的 markdown 文件。在该文件中就可以看到生成的文档了。
总结
通过使用 jsdoc-rtd，我们可以非常方便地将注释转换为文档，提高开发效率。同时，注释也让代码更加清晰易懂，适合团队协作开发。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005640b81e8991b448e148c