Jigsaw的API文档编写方法、规则、约定

本文介绍Jigsaw的API文档编写方法、规则、约定。

目录

文档写在哪?

Jigsaw的所有API相关的文档全部编写对应的代码中,以文档注释的方式编写,例如

/**
 * 总体说明
 */
export interface IAjaxComponentData {
    /**
     * 属性说明
     */
    busy: boolean;
    /**
     * 方法说明
     * @param {string} url 参数说明
     * @returns {Observable<any>} 函数返回值说明
     */
    fromAjax(url?: string): Observable<any>;
    
}

在构建版本的时候,文档构建工具会自动提取出这些文档,并组织和合并成合适的结构,方便ued网站使用。

如何编写?

如前文例子所示,根据文档所在位置的不同,主要分为如下几个类型:

  • 总体说明部分
  • 属性说明部分
  • 方法说明部分
  • 参数说明部分
  • 函数返回值说明部分

虽然文档类型众多,但是文档编写所采用的格式都是一样的,全部采用markdown格式书写文档。除此之外,你还需要了解一下文档tag文档中的变量以及文档中的链接小节。

文档自动发现

由于Jigsaw的API非常多,并且其中相当一部分API有继承、接口实现关系,Jigsaw的文档工具支持帮助API自动发现已有文档,在无更具体的api时,文档工具会往上追溯取最近一个有血缘关系的api的文档。这样可以大大减少文档在api之间多次拷贝,时长日久演进过程中,出现漏更新,进而导致误导应用使用的后果。虽然手工创建链接可以避免文档拷贝,但是手工维护这些链接工作量也不小,况且不停的链接跳转会导致文档阅读体验下降。

文档自动发现可以覆盖除了“总体说明”部分的其他所有文档。这是有意为之的,我们认为,一个类之所以被创建出来,肯定是有它独特的作用的(即使是为了语义),因此每个类的总体说明必然不同,因此,文档工具故意避开总体说明部分自动发现。

文档自动发现的一些约定(坑)

  1. 尽可能在接口、基类上编写详细的文档,且接口的优先级高于类。道理很简单,越靠近根部的文档会覆盖越多的子类,反过来说,子类需要独立编写的文档就越少。
  2. 子类实现接口方法、或者覆盖父类的方法时,请务必保持参数名字一致,这样才可以在子类中自动发现父类上的文档。这可能是最大的一个坑了。这是由于文档工具实现机制决定的,文档工具追溯类的血缘关系靠的不是编译器给出的信息,而是靠静态语法分析,因此它难以重根本上了解父子类中两个方法是否有血缘。

文档tag

这里介绍文档工具能够支持的JS文档标记。

所有可以被支持的JS文档标记以及用法介绍在这里可以找到。其中@link@example这2个不建议使用,而是建议采用markdown风格的链接和代码块来书写。

常用的罗列如下

  • @param 用于定义一个方法的参数,语法为 @param {type} var descriptions
  • @returns 用于定义一个方法的返回值,语法为 @returns {type} descriptions;特别注意,最后有个s!webstorm自动生成的JS标记有时候没有加上s。

文档中的变量

为了尽可能自动化生成更多的文档以解脱人的时间投入,文档工具支持一些变量。文档变量的使用语法为:

$var = value

其中var是变量名,value是该变量的值,是一个字符串。如果同一个变量有多个值,则配置多行,文档工具会自动将其合并为一个数组:

$var = value1
$var = value2
$var = value3

扩展:之所以使用$作为特殊字符而不用@是因为JS文档解析工具的约束导致的。@开头的自定义标记无法生成文档。

已经支持的所有变量如下:

  • $demo 将一个demo与当前文档关联起来
    • 它的值是demo的url,例如 $demo = data-encapsulation/array-ajax
    • 允许出现在总体部分、属性部分、方法部分;
    • 支持多值;
  • $since 用于标记当前api可用的起始版本
    • 它的值是一个版本号,例如 $since = v1.1.4
    • 允许出现在总体部分、属性部分、方法部分;
  • $deprecatedFrom 用于标记当前api被废弃的起始版本
    • 它的值是一个版本号,例如 $deprecatedFrom = v1.1.4
    • 允许出现在总体部分、属性部分、方法部分;
    • 常常与$replacement变量结伴使用;
  • $replacement 用于指明被废弃的api的替代方案。
    • 它的值是一段代码,例如 $replacement = touchValueByRow()
    • 允许出现在总体部分、属性部分、方法部分;
    • 必须与$deprecatedFrom结伴使用,如果所在区域的文档中未出现$deprecatedFrom,则此变量无效;

文档中的链接

同样的,为了减少人编写文档的投入和链接的有效性,文档工具能够自动识别文档中可识别的类型,并自动给加上超链,详见这个issue

例如以下这段文档:

/**
 * Jigsaw的数据总体分成两大分支:
 * - `ArrayCollection` 这个分支只关注数组类型的集合;
 * - `GeneralCollection` 这个分支只关注通用的key-value结构(即JSON对象)的集合;
 * ...
 */

文档工具可以将文档中的行内代码块 `ArrayCollection` 和 `GeneralCollection` 加上链接,注意只有行内代码块才会被自动转换。

因此,在编写文档的时候,尽量的给已知类型设置为行内代码块。

使用文档工具

执行如下命令

# 我们需要依赖[compodoc](https://github.com/compodoc/compodoc)来生成基础数据
npm install -g @compodoc/compodoc@1.0.9
git clone https://github.com/rdkmaster/jigsaw.git
cd jigsaw
sh build/scripts/doc-generator/generate.sh /path/to/output/doc

执行成功之后,就会在 /path/to/output/doc 目录下生成所需的文档了

原文链接 https://github.com/rdkmaster/jigsaw/wiki/Jigsaw-API-Documentation-Specification

http://rdk.zte.com.cn 正在改版,新的文档也将在改版之后一起上线,欢迎关注。

厉害厉害,加油!

顶顶顶

登录后回复

与 Angular开发者 的连接断开,我们正在尝试重连,请耐心等待