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
全局安装:

npm i -g @compodoc/compodoc

或局部安装:

yarn add -D @compodoc/compodoc
// or
npm i -D @compodoc/compodoc

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

"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"
}

执行文档生成:

npm run compodoc
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 定义声明,并标注主要参数的含义
一个示例:

<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 {}
}

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

  • https://compodoc.github.io/website/guides/jsdoc-tags.html
  • JSDOC http://www.css88.com/doc/jsdoc
  • JSDoc support in JavaScript

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

compodoc -h

Usage: index-cli [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 表现在使用较为灵活,对外开放接口丰富,支持插件扩展,具有非常强的定制性。

  • https://github.com/compodoc/compodoc
  • https://compodoc.github.io/website
  • JSDOC http://www.css88.com/doc/jsdoc

如何将Angular文档化? https://segmentfault.com/a/1190000009496844

作者:志文工作室

原文地址:https://lzw.me/a/angular-api-compodoc.html