在前端开发中，我们经常需要编写公共组件，并且需要文档来描述组件的使用和属性。但是手动编写文档是一件繁琐的工作，为了解决这个问题，我们可以使用 propdoc 这个 npm 包。
propdoc 是什么?
propdoc 是一个基于注释自动生成文档的工具。你只需要为你的组件或函数添加注释，就可以自动生成属性和方法文档。
安装 propdoc
使用 propdoc 首先需要安装。
打开终端，并输入以下命令来安装 propdoc。
npm install propdoc --save-dev
使用 propdoc 生成文档
在项目的根目录下，我们创建一个名为 “scripts” 的文件夹，并在该文件夹中创建一个名为 “generate-docs.js” 的文件，内容如下：
-- -------------------- ---- -------
----- ------- - -------------------
----- ------ - ---------
----- ------- - -
-------- -
----- --- --------- ---------
-------- --------
------------ -- ------- -- -------- ------------
----------- ------------------------------------------------------
--
---- --------
---------- --------------------------------------------
------- ---------
--
---------------- -- -- -
-------------------------- -------------
---上述代码中，我们首先导入 propdoc 包，指定生成的文档输出到 “./docs”目录。然后定义了一个 options 对象，其中包含以下属性：
- project：关于项目的描述信息。
- src：组件源代码所在的目录。
- templates：使用的文档模板。
- output：生成的文档输出目录。
运行以下命令来生成文档：
node ./scripts/generate-docs.js
生成的文档将会保存在 “./docs” 目录下。
代码注释与生成规则
propdoc 默认支持多种语言注释，包括 JavaScript、TypeScript、CoffeeScript、SCSS、LESS、Stylus、Pug 等，因此只需要在组件或函数的注释中添加特定的标识，propdoc 就可以自动解析出属性和方法。
在注释中，我们需要添加以下标识：
/** * @props * @name [String] - 组件名称 * @desc [String] - 组件描述 */
上述代码中，“@props” 表示这是一个属性文档，后面的 “@name” 和 “@desc” 表示属性的名称和描述。
还可以添加其他的标识，例如 “@method”、“@argument”、“@returner” 等，根据需要自由组合。
下面是一个简单的示例：
-- -------------------- ---- -------
---
- ------
- ----- ------
- ----- - ------ ----------
-
- --------
- ------- ------------ --- --
--
----- ------ ------- --------------- -
-------- -
----- - ----- - - -----------
------ ------------------------
-
-
---------------- - -
------ ----------------------------
--
------ ------- -------在上述代码中，我们使用注释标识指定了按钮组件的属性和描述，并在示例中说明了如何使用按钮组件。
使用 propdoc 生成文档后，我们可以看到生成的文档已经包含了组件的属性和描述信息。
总结
使用 propdoc，我们可以快速生成组件文档，避免手动编写文档的繁琐工作。在编写时，只需要按照规则编写注释即可，省去了很多时间。如果想要更深度的学习，可以查看 propdoc 官网的文档，了解更多高级用法。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005739e81e8991b448e9946