Angular 文档生成：使用 compodoc 生成 Angular2+ 源码组件的 API 文档

2018-05-11 0 条评论 4,148 次阅读 被赞了 4 次
目录
[隐藏]

compodoc 是针对 angular2+ 设计的 API 文档生成工具，其最大的特点是使用简单，生成文档全面美观。

1 compodoc 的优缺点

API 文档主要的作用一般有：

  • 方便快速了解整体的模块、组件依赖、项目架构等
  • 方便 API 文档快速查阅
  • 利于重复方法、变量等的分析，优化项目结构( Miscellaneous)
  • 项目质量跟踪，文档覆盖率统计分析(Documentation coverage)
  • more…

1.1 compodoc 的特点

  • 命令行方式，使用简单，傻瓜式操作
  • 生成文档包含模块、组件、路由等的依赖结构图，简洁清晰
  • 每个组件都会生成 DOM 树，分析方便直观
  • 每个组件都可以书写独立 markdown 格式文档，自动读取和生成到文档
  • 文档覆盖率统计
  • 文件级局部变量、方法分布统计
  • mroe…

1.2 compodoc 的不足

  • 不直接支持 node API 调用，没有插件化功能，如需自定义扩展会比较复杂
  • html 结构的 DOM 树暂时不支持 pug 等预编译语言(官方表示在 1.2 版本会提供支持)
  • more…

2 compodoc 生成的文档主要内容

  • Overview 项目主要内容统计概览。图形化展示主要模块、组件、指令等
  • README 由项目根目录 README.MD 生成
  • Dependencies 项目第三方依赖列表
  • Modules 所有模块的列表。生成有模块依赖图列表
  • Components 独立组件
  • Directives 独立指令
  • Classes 独立类列表
  • Injectables 使用 Injectables 装饰器修饰的独立类列表
  • Interfaces 所有接口定义列表
  • Pipes 管道列表
  • Routes 路由树图。路由定义需指定类型为 Routes (从 @angular/router 导入)
  • Miscellaneous 其他杂项内容集合。根据这里的内容，可以分析分散的重复定义的内容，不合理的杂项定义等
  • Documentation coverage 文档覆盖率信息

3 在项目中配置和使用compodoc

全局安装：

1
npm i -g @compodoc/compodoc

或局部安装：

1
2
3
yarn add -D @compodoc/compodoc
// or
npm i -D @compodoc/compodoc

配置文档生成命令到 package.json 的 scripts 中。示例参考：

1
2
3
4
5
6
7
8
"scripts": {
    "prod": "npm run build:prod && npm run compodoc",
    "build:prod": "",
    "compodoc": "npm run compodoc:build && npm run compodoc:serve",
    "compodoc": "shx rm -rf ./compodoc/*",
    "compodoc:build": "compodoc ./src -d ./compodoc -p tsconfig.json --theme stripe --hideGenerator --includes ./docs --exclude ./src/lib -n \"NBOP2.0 FRONT Documentation\"",
    "compodoc:serve": "compodoc -d ./compodoc --serve --port 6666 --open"
}

执行文档生成：

1
npm run compodoc
1
npm run compodoc:serve

生成的文档效果示例(gitbook 风格)：

https://compodoc.github.io/compodoc-demo-todomvc-angular/

4 项目使用 compodoc 时的编码与注释规范参考

4.1 文件目录规范

  • 指定对 src/app 目录下文件作文档生成
  • 如有必要，组件目录下，应建立与组件同名的 xx.compent.md 组件使用说明文档；公共组件必须书写说明文档，并保持同步更新
  • 如有必要，可指定额外的 markdown 文档目录。目录下应当包含 summary.json 文件，指定文档树及各文档的路径和名称 tips-and-tricks
  • more…

4.2 编码及注释规范

编码应参考 jsdoc 规范，方法应当写详细的注释。主要有：

  • 注释以单行 /** 开头，才会被 compodoc 识别
  • 由于 TypeScript 的定义会自动识别参数类型，jsdoc 风格的参数类型可省略
  • @returns 定义返回值的描述
  • @ignore 表示忽略该方法或组件的定义，不在文档中生成
  • @link 语法可以定义链接另一个方法、文档或外部链接
  • @param 定义一个参数的类型和描述
  • @example 定义一个示例用法
  • 路由定义：路由定义应指定类型为 Routes (从 @angular/router 导入)，以便生成路由树状图
  • 参数：简单的参数，应写明作用，可取值等；复杂参数应使用 Interface 定义声明，并标注主要参数的含义

一个示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<br>/**
 * 根组件
 */
@Component({...})
export class AppComponent {
    /**
     * @ignore
     */
    ignoredProperty: string;
 
    /**
     * @ignore
     */
    @Input() ignoredInput: string;
 
    /**
     * 属性的注释
     */
    tom: string;
 
    /**
     * 将传入的字符串参数格式化为数字
     * @param {string} target  该参数具体说明参考 {@link Todo} {@link http://lzw.me/doc/target|target}
     * @returns target 处理后的数字格式
     * @example
     * 一个使用示例如下
     * ```js
     * processTarget('yo')
     * ```
     */
    function processTarget(target:string):number {}
}

更多注释规范细节参考文档：

5 compodoc 功能参数参考(版本 1.1.1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
compodoc -h
 
  Usage: index-cli <src> [options]
 
  Options:
 
    -V, --version                             版本信息
    -p, --tsconfig [config]                   指定 tsconfig.json 文件路径
    -d, --output [folder]                     指定文档输出路径 (默认为: ./documentation/)
    -y, --extTheme [file]                     指定额外加载的样式文件(用于自定义主题)
    -n, --name [name]                         生成文档的标题 (默认为: pageage.json 的 name 值 + documentation)
    -a, --assetsFolder [folder]               需要复制到文档目录的额外资源文件
    -o, --open                                生成后打开文档
    -t, --silent                              静默模式，生成过程不打印日志
    -s, --serve                               启动 http server (默认 http://localhost:8080/)
    -r, --port [port]                         指定 http server 的端口 (默认: 8080)
    -w, --watch                               监听文件变动，实时重新生成
    -e, --exportFormat [format]               指定输出内容的格式 (json, html) (default: html)
    --theme [theme]                           指定主题，默认为 'gitbook' (laravel, original, material, postmark, readthedocs, stripe, vagrant)
    --hideGenerator                           生成文档底部隐藏 Compodoc 的链接
    --toggleMenuItems <items>                 Close by default items in the menu values : ['all'] or one of these ['modules','components','directives','classes','injectables','interfaces','pipes','additionalPages'] (default: all)
    --includes [path]                         额外指定一个包含 markdown 文档的路径(注意：该路径目录下应包含 summary.json 文件)
    --includesName [name]                     额外指定的 markdown 文档的目录名称 (默认为: Additional documentation)
    --coverageTest [threshold]                文档覆盖率测试阈值 (默认为 70)
    --coverageMinimumPerFile [minimum]        每个文件的文档覆盖率最小值 (默认为 0)
    --coverageTestThresholdFail [true|false]  文档覆盖率不达标时的动作 (true: error, false: warn) (default: true)
    --disableSourceCode                       生成文档中不包含文件源码项
    --disableDomTree                          不生成 DOM 树结构图
    --disableGraph                            不生成模块依赖图
    --disableCoverage                         不生成文档覆盖率报告
    --disablePrivate                          不生成私有属性或方法的文档说明
    --disableProtected                        不生成保护属性或方法的文档说明
    --disableInternal                         不生成 `@internal` 修饰的内部属性或方法文档说明
    --disableLifeCycleHooks                   不生成 Angular 生命周期钩子的文档说明
    --disableRoutesGraph                      不生成路由结构图
    --customFavicon [path]                    指定一个自定义的 favicon 站点图标
    --gaID [id]                               谷歌分析 ID
    --gaSite [site]                           谷歌分析的名称 (default: auto)

6 更多参考

compodoc 上手简单、功能完善，可满足大多数 Angular 项目的文档生成需要。

另外，如果 compodoc 不能满足你的需求，可以考虑一下 Angular 官方出品的 API 文档生成工具 Dgeni。Dgeni 表现在使用较为灵活，对外开放接口丰富，支持插件扩展，具有非常强的定制性。

相关文章:

Default ThumbnailAngular 9 新特性及 Angular 8 升级至 Angular 9 参考 Default ThumbnailAngular 中实现自定义组件的双向绑定的两种方法 升级至 Angular 13+ 后开发模式太慢的原因及构建性能优化 Default ThumbnailAngular 项目升级至 Angular6 一种自定义 Angular-cli 6.x/7.x 默认 webpack 配置的方法 Default ThumbnailAngular 单元测试框架由 karma 迁移为 Jest 实践 Default Thumbnail在 Angular-cli 中引入 simple-mock 实现前端开发 API Mock 接口数据模拟 Default ThumbnailHTML5 本地存储 localStorage、sessionStorage 的遍历、存储大小限制处理 Default Thumbnail使用 JSDoc 与 docstrap 生成 JavaScript 项目 API 文档 Default Thumbnailnodejs 执行失败报错 “JavaScript heap out of memory” 的解决办法 Default Thumbnail使用 commitlint 约束项目 Git 代码提交描述信息格式规范 Default Thumbnail升级至 Angular8 及实现自定义 webpack 配置的方案
点赞 (4)
知识共享许可协议
本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

Captcha Code