前言
随着前端技术的快速发展，前端开发人员要求的技能也日益丰富。其中，对于组件库开发的需求越来越高。在组件库开发中，组件的文档是必不可少的一部分。文档管理的好坏将直接影响到组件库的易用性。这时候，我们需要一种既能方便编写组件文档，又能够规范化生成文档的工具。其中，使用 js-docgen 这个 npm 包是不错的选择。
js-docgen 是什么
js-docgen 是一个用于生成代码的详细文档的 npm 包。你可以使用 js-docgen 对你的 JavaScript 代码进行解析，并从注释中提取特定说明并生成文档。
使用步骤
- 安装 js-docgen。
npm install -g jsdoc
- 在代码中书写注释，并在注释中加入 jsdoc 格式的注释。
-- -------------------- ---- ------- --- - ------ - ------ -------- - - -- - ------ -------- - - -- - -------- -------- - -------- -- -------- ------ -- - ------ - - -- -
- 运行 js-docgen 并生成文档。
jsdoc add.js
- 查看生成的文档。
打开 out/index.html 文件，可以看到我们生成的文档已经在浏览器中展现。
jsdoc 注释规则详解
在 jsdoc 注释中，您可以使用多种标记来描述你的代码。在下面的例子中，将会讲解几个常见的 jsdoc 注释的写法。
@param
@param 标记文档提供给函数中传入的参数。可以使用该标记多次来描述每个参数。如下：
-- -------------------- ---- ------- --- - ------ - ------ -------- - - -- - ------ -------- - - -- - -------- -------- - -------- -- -------- ------ -- - ------ - - - -
@returns
@returns 标记文档提供了函数能返回的内容信息。可以使用该标记一次来描述返回值。如下：
-- -------------------- ---- -------
---
- ------
- ------ -------- - - --
- ------ -------- - - ------ -
- -------- -------- - --
--
-------- --------- -- -
-- -- -- -- -
----- --- ------------ ---
-
------ - - -
-@throws
@throws 标记文档描述了函数可能抛出的异常。可以使用该标记多次来分别描述每个异常。如下：
-- -------------------- ---- -------
---
- ------
- ------ -------- - - --
- ------ -------- - - ------ -
- -------- -------- - --
- ------- ------- - ---- - --------
--
-------- --------- -- -
-- -- -- -- -
----- --- ------------ ---
-
------ - - -
-@example
@example 标记文档描述如何使用此函数。可以使用该标记多次来分别描述每个使用案例。您可以简单地写入您要展示的代码，jsdoc 将自动将其包装在代码块中。如下：
/**
* @example
* add(1, 2) // 返回 3
* add(2, 3) // 返回 5
*/
function add(a, b) {
return a + b
}总结
本文介绍了 npm 包 js-docgen 的使用方法，详细讲解了 jsdoc 注释的基本规则和书写步骤。js-docgen 是一款十分实用的 npm 包，可以方便地将您的代码转化为规范的文档，使您的组件库开发更加轻松。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600560a981e8991b448dee87