陈旭 - Angular开发者

RE: ng的定时任务请问是如何做的?rx的还是window. setInterval?

都可以，使用setInterval最简单了，推荐。

发布在 questions •

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

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

发布在 posts •

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之间多次拷贝，时长日久演进过程中，出现漏更新，进而导致误导应用使用的后果。虽然手工创建链接可以避免文档拷贝，但是手工维护这些链接工作量也不小，况且不停的链接跳转会导致文档阅读体验下降。

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

文档自动发现的一些约定（坑）

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

文档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

发布在 posts •

RE: 译文 | Angular中的AoT编译

使用angular-cli的话，很简单：

ng build -aot

发布在 posts •

Jigsaw发布新版本v1.1.0啦！新增 2 个布局器和 1 个组件

新特性 / New Features

重磅功能：增强j-box布局功能，支持用户在界面上拖拽调整布局尺寸，详见这里
重磅功能：增加j-editable-box组件，纯数据驱动的布局方式，更加灵活，轻松实现所见即所得的布局效果，详见这里
新组件：增加j-notification组件，更加灵活&友好的消息提示功能，详见这里
https://github.com/rdkmaster/jigsaw/issues/481 PageableTableData支持post请求

破坏性修改 / Breaking Changes

无 / none

优化 / Modified

https://github.com/rdkmaster/jigsaw/issues/349 增加图例和饼图间距的配置，解决描述文字模糊的问题
https://github.com/rdkmaster/jigsaw/issues/467 table的滚动条加个最小长度
简化PopupService.setPosition()的参数列表，提升易用性