Angular 工具篇之文档管理

栏目: 编程语言 · AngularJS · 发布时间: 6年前

内容简介:Angular 工具篇系列教程目录:本文我们将介绍在安装

Angular 工具篇系列教程目录:

本文我们将介绍 Compodoc 这款工具,它用于为 Angular 应用程序生成静态文档。Compodoc 能够帮助 Angular开发人员为他们的应用程序生成清晰且有用的文档,这使得参与应用程序开发的其它成员也可以轻松了解当前应用程序或库的特性。

在安装 Compodoc 之前,我们先来简单了解一下它的特点:

  • 生成的文档结构清晰。
  • 支持多种主题风格,比如 laravel, original, material, postmark 等。
  • 支持快速检索,基于强大的 lunr.js 搜索引擎。
  • 支持 JSDoc 高亮,支持 @param , @returns , @link , @ignore@example 标签。
  • 支持文档覆盖率统计。
  • 对 Angular CLI 友好,支持 Angular CLI 创建的项目。
  • 离线化,无需服务器,不依赖线上资源,完全脱机生成的文档。

安装 compodoc

首先我们以 local 模式进行安装:

$ npm install --save-dev @compodoc/compodoc

当然你也可以选择 global 模式进行安装:

$ npm install -g @compodoc/compodoc

然后我们在项目的 package.json 中添加以下配置:

"scripts": {
  "compodoc": "./node_modules/.bin/compodoc -p src/tsconfig.app.json"
}

配置完 npm script,我们就可以运行以下命令:

$ npm run compodoc

compodoc 命令支持很多选项,这里我们简单介绍几个比较常用的选项:

  1. -p, –tsconfig [config] —— 指定 tsconfig.json 文件的路径
  2. -n, –name [name] —— 文档的标题
  3. -s, –serve —— 启动本地文档服务器(默认地址为 http://localhost:8080/)
  4. -r, –port [port] —— 指定本地文档服务器的端口
  5. -w, –watch —— 启动监听模式,文件发生异动时自动编译
  6. –theme [theme] —— 设置主题风格,支持 laravel, original, material, postmark, readthedocs, stripe, vagrant。你可以访问 compodoc - themes 查看相关主题风格。
  7. -d, –output [folder] —— 指定文档的输出目录
  8. -h, –help —— 显示帮助信息

若需查看完整的配置项,可以浏览 compodoc - usage

文档注释

comments

Compodoc 使用 TypeScript AST 解析器和它的内部 API,因此注释必须是合法的 JSDoc 注释。

  1. 有效的注释
/**
 * Supported comment
 */
  1. 无效的注释
/*
 * unsupported comment
 */

/*
  unsupported comment
 */

// unsupported comment

通过观察上面的示例,我们可以得出一个结论,只有以 /** 开头的注释,才能被 compodoc 识别。

JSDoc Tags

由于 TypeScript 编译器的限制 目前 Compodoc 只支持以下的 JSDoc 标签:

  • @returns —— 描述返回值

  • @ignore —— 表示标记的内容永远不会出现在文档中

  • @param —— 定义一个参数的类型和描述
  • @link —— 定义链接另一个方法、文档或外部链接
  • @example —— 定义一个示例用法

了解完上述标签,我们来看一个比较完整的示例(来源于 ionic-code-documentation

import { Injectable } from '@angular/core';
 
/**
  Provider for super difficult math operations
*/
@Injectable()
export class MathProvider {
 
  /**
    Value of the last operation
  */
  storedValued: number;
 
  /**
   * @ignore
   */
  constructor() { }
 
  /**
   * Performs a very special operation
   * 
   * @example
   * Simply call it with 2 numbers: 
   * getResult(2, 3)
   * 
   * @param {number} a First number
   * @param {number} b Second number
   * @returns The sum of a and b
   */
  getResult(a: number, b: number) : number {
    let sum = a + b;
    this.storedValued = sum;
    return sum;
  }
}

其实 Compodoc 除了能够根据 JSDoc 标签生成对应的文档之外,它还能为我们自动生成项目概况、路由信息、组件信息及文档覆盖率等。感兴趣的同学,可以访问线上的示例 compodoc-demo-todomvc-angular 详细了解情况。

总结

本文简单介绍了如何利用 Compodoc 这款工具,为 Angular 应用程序生成静态文档,Compodoc 基本上能够满足我们的需求。对 Angular 项目来说,除了 Compodoc 之外,你也可以考虑使用谷歌官方出品的 API 文档生成工具 Dgeni ,它对外开放了丰富的接口,还支持插件扩展,具有非常强的定制性。


以上就是本文的全部内容,希望本文的内容对大家的学习或者工作能带来一定的帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

十亿美金的教训

十亿美金的教训

林军 唐宏梅 / 浙江大学出版社 / 2011-5 / 39.00元

《十亿美金的教训》内容简介:创业者个人能力欠缺、团队涣散、经营方向把握不当、资金动用失措以及时局不利……这其中有哪一个细节被忽视,都可能是失败的导火索! 国内二十年互联网风云,有人成功,有人失败。两种结果,不同方向,却往往只是一线之隔。他们留给我们怎样的教训与启示?后来者要怎样才能跳出失败之殇? 《十亿美金的教训》选取了互联网十个经典的失败案例,并深层解读这些互联网企业与创业者们从成功......一起来看看 《十亿美金的教训》 这本书的介绍吧!

HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

URL 编码/解码
URL 编码/解码

URL 编码/解码

HSV CMYK 转换工具
HSV CMYK 转换工具

HSV CMYK互换工具