Skip to content

Jigsaw API Documentation Specification

Jump to bottom
陈旭 edited this page Mar 24, 2018 · 9 revisions

本文介绍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。
  • @deprecated 用于标记一个方法、属性、类型等为过时状态。注意这个标记是给IDE用的，由于文档生产工具的问题，这个标记并未能体现到生成的文档中，需要使用$deprecatedFrom这个文档变量替代。

文档中的变量

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

$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，则此变量无效；

文档变量还有一个特殊形式：内联demo链接。在api文档的行文过程中，有时候需要插入一个demo链接已帮助读者理解文档描述，可以在文档中插入内联demo链接，举例：

... 这个组件的用法详见[这个demo]($demo=table/renderer) ...

其中$demo=table/renderer就是文档变量的另一种用法。

文档中的链接

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

例如以下这段文档：

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

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

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

使用文档工具

执行如下命令

# 我们需要依赖[compodoc](https://github.com/compodoc/compodoc)来生成基础数据
npm install -g @compodoc/[email protected]
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 目录下生成所需的文档了

Clone this wiki locally