编码规范#

C API规范#

C API均以 luat_ 开头, 后接模块名, 然后是方法名
使用抽象的类型定义, 例如不使用int, 使用uint32_t
使用下划线命名方式

举例

LUA_API void* luat_heap_alloc(void *ud, void *ptr, size_t osize, size_t nsize);

Lua API 规范#

命名规范#

库名称，全部使用小写字母
库内的常量，全部使用大写字母命名，以下划线分割
库内的接口，使用驼峰命名，首字母小写，禁止使用下划线分隔的写法
- 判断是否符号要求的接口，使用is开头
- 打开操作使用open开头
- 关闭操作使用close开头
- 初始化操作使用setup开头
- 更改状态操作使用set开头
- 获取状态操作使用get开头
- 发送与接收接口
  - 同时存在send/recv与read/write时
    - 发送原始数据操作使用send开头
    - 接收原始数据操作使用recv开头
    - 发送c代码处理过的信息操作使用write开头（如按寄存器地址写i2c）
    - 接收c代码处理过的信息操作使用read开头
  - 只存在send/recv与read/write的其中一种时
    - 按习惯进行编写（如串口使用的是read/write，而socket使用的是send/recv）
- 异步接口（使用C接口实现Task等待功能适配的接口）使用task开头

举例

local spiDevice = spi.setupDevice(0,17,0,0,8,2000000,spi.MSB,1,1)
i2c.isExist(id)
adc.open(id)
camera.setup(...)

交互规范#

返回结果的接口#

只可能返回成功或失败的接口
- 使用true返回，代表成功
- 使用nil,"reason"返回，代表失败
- 避免使用纯数字作为成功与否的结果返回
会返回进度的接口
- 返回成功执行进度的数字（如串口、spi发送成功的数据长度）
会返回具体数据的接口
- 如果返回的是长度，没数据就使用0
- 如果返回的是string，没数据就使用长度为0的字符串
- 如果使用nil代表接收失败，需要在接口文档里的返回值部分加粗提醒
需要等一段时间才能获取结果的接口
- 如果可以实现非阻塞
  - 可以使用回调方式给用户上报事件
  - 可以适配C接口实现Task等待功能方式提供可在任务中运行的异步接口（实现方式参考此页）
  - 尽量避免使用特定的topic让用户手动调用sys.waitUntil的方式进行适配
- 尽量避免添加阻塞时间较长的接口

需要传入GPIO的接口#

端口号不存在时，使用负数来代表，尽量避免使用特定的正数或0（有些MCU存在GPIO_0）
其他待定

Git 提交规范#

主分支 master
开发分支, 由开发者自行开立, 命名遵循: issue_xxx, feature_xxx 前缀
提交时的commit
严禁使用 git push -f 执行强制推送

add:  xxxx   添加功能,特性
update: xxx  修改功能,特性, 改变行为
remove: xxxx 删除功能,特性
fix:  xxxx   明确修复指定的issue, 贴上#issue完整编号
revert: xxx  回滚某个操作

特殊技巧：GitHub与Gitee均会自动识别#号开头，后面附带issue编号的语法（前后需空格），会自动与指定issue关联。并且如果commit内容中有close和fix等字样，会自动关闭该issue。如： close #12345

Lua接口注释规范#

为了能自动生成接口文档，需要严格按照下面的格式对接口进行注释

在C文件内的接口#

在文件的最上方，格式如下（如果无此开头，文件不会被扫描）：

/*
@module  模块的名称，如：adc
@summary 模块的简短描述信息，如：数模转换
@version 版本号，可选
@data    日期，可选
@demo    可选，指LuatOS/demo中的文件夹名称
@video   可选，该库的视频教程网址
@tag     可选，该库启用的宏定义标记，如：LUAT_USE_ADC
@usage
--这个库的简易使用例子，可选
--可以写多行
*/

在Lua内可调用的函数，格式如下：

/*
第一行写明函数的用途，如：打开adc通道
@api module.function(调用时用到的完整函数名)
@tag 可选，如果接口只支持部分芯片，此处填上该库启用的宏定义标记，如：LUAT_USE_ADC
@string 第一个参数，@后跟参数类型，空格后跟参数解释。如有默认值，需要全部写明
@number 第二个参数
@table 第三个参数
...根据实际，列出所有参数
@return 类型 返回的第一个值，必须按格式填写，如有默认值，需要全部写明
@return string 返回的第二个值，类型为string
...根据实际，列处所有返回值
@usage
--使用的例子，可多行
lcoal a,b,c = module.function("test",nil,{1,2,3})
lcoal d,e,f = module.function("abc",nil,{1,2,3})
*/
static int l_module_function(lua_State *L) {
    //一堆代码
}

静态常量，可在常量附近添加以下格式的注释：

//@const 常量名 类型 解释
/*比如*/
//@const NONE number 无校验

/*只需写常量名
  会自动在文档中生成 库名.常量名 的结果 */

在Lua文件内的接口#

在文件的最上方，与c接口格式的基本相同，只是多了库例子，格式如下：

--[[
@module  模块的调用名
@summary 模块的简短描述信息
@version 版本号，可选
@data    日期，可选
@author  作者名，可选
@demo    可选，指LuatOS/demo文件夹中的demo名称
@video   可选，该库的视频教程网址
@usage
--这个库的使用例子
--可以写多行
]]

可调用的函数，与c接口格式的基本相同，如下：

--[[
第一行写明函数的用途，如：打开adc通道
@api module.function(调用时用到的完整函数名)
@string 第一个参数，@后跟参数类型，空格后跟参数解释。如有默认值，需要全部写明
@number 第二个参数
@table 第三个参数
...根据实际，列出所有参数
@return 类型 返回的第一个值，必须按格式填写，如有默认值，需要全部写明
@return string 返回的第二个值，类型为string
...根据实际，列处所有返回值
@usage
--使用的例子，可多行
--巴拉巴拉
]]

静态常量，可在常量附近添加以下格式的注释：

--//@const 常量名 类型 解释
--比如
--//@const NONE number 无校验

--只需写常量名
--会自动在文档中生成 库名.常量名 的结果

sys_pub发布的topic描述规范#

在lua_call或lua_pushstring附近，加上对此消息的相关解释

注意，第一行的/*前面不能有任何缩进

        lua_getglobal(L, "sys_pub");
/*
@sys_pub wlan（该topic所属的模块）
第一行写明消息的用途，如：WIFI扫描结束
WLAN_SCAN_DONE  （该topic的完整名称）
@string 第一个传递的数据，@后跟数据类型，空格后跟数据解释，如果没有就别写这几行
@number 第二个数据
...根据实际，列出所有传递的数据
@usage
--使用的例子，可多行
sys.taskInit(function()
    xxxxxxxxxx
    xxxxxxx
    sys.waitUntil("WLAN_SCAN_DONE")
    xxxxxxxxxx
end)
*/
        lua_pushstring(L, "WLAN_SCAN_DONE");
        lua_call(L, 1, 0);