在前端开发中，文档是不可或缺的一部分，而 compodoc 作为一个强大的文档生成工具，可以从代码中自动生成丰富的文档，让文档的编写变得更加高效和规范化。本文将介绍如何使用 npm 包 compodoc 生成文档并深入解析其使用方法。
安装
在使用 compodoc 之前，我们需要先进行安装。通过 npm 安装可全局使用 compodoc：
npm install -g @compodoc/compodoc
此时我们已经全局安装了 compodoc。
使用
生成文档
生成文档很简单，只需要在项目根目录下执行如下命令：
compodoc -p tsconfig.json
其中 -p 表示需要传递一个项目的 tsconfig.json 文件，用于 compodoc 自动生成文档。
命令执行完成后，compodoc 会在项目根目录下生成一个 documentation 文件夹，其中包括我们生成的文档。将其中的 index.html 文件用浏览器打开即可查看生成的文档。
配置
compodoc 支持多种配置，我们可以通过命令行指定不同的参数来改变生成文档的样式，比如在命令中指定 CSS 文件路径：
compodoc -p tsconfig.json --theme ./path/to/theme.css
或者指定文档输出目录：
compodoc -p tsconfig.json -d ./path/to/documentation
compodoc 支持的参数非常多，具体可以查阅文档。
注释
compodoc 能够从代码中自动生成文档，这需要我们对代码进行一些注释。注释是使用 JSDoc 格式完成的，主要包括类、方法、属性等。
对于一个常见的组件类注释，示例如下：
-- -------------------- ---- -------
---
- --------- --- ---------- ---- ------------
- --------
- --------- --------------------------------
--
------------
--------- -----------
------------ ------------------------
---------- -------------------------
--
------ ----- ------------- ---------- ------ -
-------- ----- ----- -- --- ---- -- --------
------------- - -
----------- ---- -
-
---
- -------- --- ------ --- -- ------
- ------- -------- --- ------ ----
--
--------- ------ -
-- ---- -- --------- ------ ----
-
-在上述示例中，我们使用 JSDoc 注释定义了组件的作用以及输入的参数与类型，并在示例部分提供了一个简单的使用案例。注释的规范化与标准化，对于后期文档生成和维护非常重要。
模块化
在一个大型的项目中，我们可能会拆分为多个模块，每个模块都有自己的代码结构和 API。使用 compodoc，我们可以将每个模块的文档分别生成，并通过 link 进行互相跳转。我们可以在 tsconfig.json 文件中如下配置：
-- -------------------- ---- -------
-
------------------ -
--------- ----------
--
----------- -
---------- -
-
------- -------
----------- -
----------------
------------------------
-
--
-
------- ---------
----------- -
------------------
--------------------------
-
-
-
-
-在 compodoc.modules 中我们配置了两个模块，分别是 Core 和 Shared，指定了它们的代码路径，并排除了测试代码。这样我们就能够生成多个模块的文档了。在每个模块的文档中，我们可以通过 link 定位到另一个模块的文档中。
结语
本文介绍了使用 npm 包 compodoc 生成文档的方法及其相关配置和注释的规范。同时讲解了模块化的使用方法。除此之外， compodoc 还支持很多高级特性，欢迎大家进一步了解。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60941