tangram的插件规范

无规矩不成方圆,在多人合作与开发中,互相协作是一个永恒的话题,tangram开发也不例外。如何将代码中的注释提取到平台文档中,如何书写能够让代码开发互不冲突,如何协作开发接口demo?这些都需要一套约定的规范来统一。

一、tangram插件文件结构规范

2.1 代码存放

插件javascript代码存放在目录 Tangram2/src/plugin/ 中;

暴露的插件方法,保存为对应的.js文件,直接存放路径:

Tangram2/src/plugin/

私有及工具类的不对外暴露方法,存放路径 :

Tangram2/src/plugin/util/

2.2 资源存放

插件所会用到的资源文件,如CSS和图片等非javascript文件,统一存放路径:

Tangram2/src/resource/

每个插件方法如果有资源文件,则在resource目录中建立一个对应的文件夹,命名规范为:

Tangram2/src/resource/plugin.xxxx/

“xxxx”为对应插件的名字,其中默认CSS,命名为“default.css”。

2.3 举例

如:插件draggable,含有一个私有方法drag,一个CSS资源文件。则文件结构为:

插件代码 Tangram2/src/plugin/draggable.js 工具方法 Tangram2/src/plugin/util/drag.js 资源文件 Tangram2/src/resource/plugin.draggable/default.css

二、tangram插件命名空间

tangram插件较为灵活,命名空间也都是插件开发者去自由选择。以下只是列出一些tangram基本的命名空间,插件开发者可以自由选择。

插件的私有工具方法,一般会扩展到 baidu.plugin.util 下。其他的方法,也可以使用对应链头的extend方法扩展到对应的链头上面。比如,想要扩展一个isCrash方法到dom上面,那么就

///import baidu.dom;
baidu.dom.extend({
    isCrash:function(){
        .....
    }
});

三、注释规范

每个代码最少要含有作者信息,接口描述,以及功能相关等。注释标记说明:

@author 作者信息 @email 联系的邮箱地址 @description 接口描述 @function 接口类型是函数 @name 接口名称 @grammar 接口使用的语法 @param 参数说明 @return 返回值说明 @example 消息描述等说明信息

接口描述的注释,要以“ /** ” (注意:是两个型号)开头,因为API平台会去根据这个标记自动抓取注释生成API文档。在 “@example”中写“示例代码:”,其下面的注释部分会自动被抓取为API文档中的示例代码文档。如图1:

alt 1图1

具体举例如下:

/*
     * @author wangxiao
     * @email  1988wangxiao@gmail.com
     */
 
    /**
     * @description 简单的拖拽方法
     * @function 
     * @name baidu.plugin._util_.drag
     * @grammar baidu.plugin._util_.drag(selector)
     * @param {Selector} selector css选择器字符串,只对第一个匹配元素操作
     * @return {Object} 返回相关实例方法的对象
     * @example 
     执行函数会立刻绑定“mousemove”事件,鼠标移动即会产生拖拽效果,
     当拖拽开始时触发“dragstart”事件,当拖拽时触发“dragging”,当拖拽结束时触发“dragend”。
 
     示例代码:
     相关CSS说明:
 
    //@description 该className会在用户拖拽某一元素时被添加到该元素上。
     .tang-draggable-dragging{
        filter:alpha(opacity=80);
        -moz-opacity:0.8;
        opacity: 0.8;
     }
*/

四、测试用例

每个插件需要补充自己的单元测试用例,tangram插件测试平台是采用Qunit单元测试工具。具体写法可以参看其他测试用例,或者Qunit官方文档。在此只对文件路径进行约束,tangram插件对应的测试用例文件路径:

Tangram2/test/plugin/xxxx.js

“xxxx”就是对应插件的文件名称,比如draggable插件:

文件路径 Tangram2/src/plugin/draggable.js 测试用例路径 Tangram2/test/plugin/draggable.js

五、Demo规范

目前Demo仍需做调整,暂不写入规范,如需写Demo,请参考其他接口。

感谢您的阅读,希望给你的开发带来帮助!