使用compodoc工具生成文档
-
全局安装compodoc工具
npm i -g @compodoc/compodoc -
compodoc还依赖于
eslint,虽然不安装也没问题。npm install eslint --save-dev -
在 package.json 中配置script命令(以下命令按需要修改
--language zh-CN配置项 日语:ja-JP)"scripts": { ..., "compodoc": "compodoc -p tsconfig.json -d ./compodoc --hideGenerator --theme postmark -w -s --port 8852 --language zh-CN --open", ... }, -
开始生成文档
npm run compodoc生成的文档默认在 工程目录下(./compodoc/ )
-
各参数解释
-h, --help 输出使用信息 -V, --version 输出版本号 -c, --config [config] 配置文件:.compodocrc,.compodocrc.json,.compodocrc.yaml或package.json中的compodoc属性 -p, --tsconfig [config] 一个tsconfig.json文件 -d, --output [folder] 存储生成的文档的位置 -y, --extraTheme [file] 外部造型主题 -n, --name [name] 文件标题 -a, --assetsFolder [folder] 外部资产文件夹,用于复制生成的文档文件夹 -o, --open 打开生成的文档 -t, --silent 在静默模式下,日志消息不会记录在控制台中 -s, --serve 提供生成的文档（默认http://localhost:8080/） -r, --port [port] 更改默认服务端口 -w, --watch 在serve和force documentation rebuild之后观察源文件 -e, --exportFormat [format] 以指定格式导出（json,html（默认）） --language [language] 用于生成文档的语言（en-US,fr-FR,zh-CN,pt-BR）（默认值:en-US） --theme [theme] 选择一个可用主题,默认为'gitbook'（laravel,original,material,postmark,readthedocs,stripe,vagrant） --hideGenerator 不要在页面底部打印Compodoc徽标 --toggleMenuItems 关闭菜单中的默认项目（默认['all']）值:['all']或其中一个['modules','components','directives','classes','injectables','interfaces' , '管道', 'additionalPages']） --navTabConfig 按所需顺序列出导航选项卡对象,其中包含两个字符串属性（“id”和“label”）。双引号必须使用'\'进行转义。可用的选项卡ID是“info”,“readme”,“source”,“templateData”,“tree”和“example”。注意:仅在适用于给定依赖项时才会显示某些选项卡 --templates [folder] Handlebars模板目录的路径,用于覆盖内置模板 --includes [path] 要包含的外部markdown文件的路径 --includesName [name] 外部降价文件的项目菜单名称（默认“附加文档”） --coverageTest 使用阈值测试文档覆盖率命令（默认为70） --coverageMinimumPerFile [minimum] 每个文件的文档覆盖率测试命令至少（默认为0） --coverageTestThresholdFail [boolean] 文档覆盖率（全局或每个文件）的测试命令将失败并显示错误或仅警告用户（true:error,false:warn）（默认值:true） --coverageTestShowOnlyFailed 仅显示覆盖测试的失败文件 --unitTestCoverage [json-summary] 要包含单元测试覆盖率,请指定istanbul JSON覆盖率摘要文件 --disableSourceCode 不要添加源代码选项卡和源代码链接 --disableDomTree 不要添加dom树选项卡 --disableTemplateTab 不要添加模板选项卡 --disableStyleTab 不要添加样式选项卡 --disableGraph 禁用依赖关系图的呈现 --disableCoverage 不要添加文档覆盖率报告 --disablePrivate 不要在生成的文档中显示私有 --disableProtected 不要在生成的文档中显示受保护 --disableInternal 不要在生成的文档中显示@internal --disableLifeCycleHooks 不要在生成的文档中显示Angular生命周期钩子 --disableRoutesGraph 不要添加路线图 --disableSearch 不要添加搜索输入 --minimal 只有文档的最小模式。没有搜索,没有图表,没有覆盖。 --customFavicon [path] 使用自定义图标 --customLogo [path] 使用自定义徽标 --gaID [id] Google Analytics跟踪ID --gaSite [site] Google Analytics网站名称（默认自动（默认:自动）） -
编码注释规范
编码应参考 jsdoc 规范 ，方法应当写详细的注释。主要有：
- 注释以单行
/**开头，才会被 compodoc 识别 - 由于 TypeScript 的定义会自动识别参数类型，jsdoc 风格的参数类型可省略
-
@returns定义返回值的描述 -
@ignore表示忽略该方法或组件的定义，不在文档中生成 -
@link语法可以定义链接另一个方法、文档或外部链接 -
@param定义一个参数的类型和描述 -
@example定义一个示例用法 - 路由定义：路由定义应指定类型为
Routes(从@angular/router导入)，以便生成路由树状图 - 参数：简单的参数，应写明作用，可取值等；复杂参数应使用
Interface定义声明，并标注主要参数的含义
- 注释以单行
示例：
/**
* 根组件
*/
@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 {}
}
