add: 为luat_base.h和luat_adc.h添加注释

luat/include/luat_adc.h

@@ -1,11 +1,39 @@
-
+/******************************************************************************
+ *  ADC设备操作抽象层
+ *  @author wendal
+ *  @since 0.1.5
+ *****************************************************************************/
 #ifndef Luat_ADC
 #define Luat_ADC
 
 #include "luat_base.h"
 
+
+/******************************************************************************
+ * luat_adc_open
+ * Description: 打开一个adc通道
+ * @param pin[in] adc通道的序号
+ * @param args[in] 保留用,传NULL
+ * @return 0 成功, 其他值为失败
+******************************************************************************/
 int luat_adc_open(int pin, void* args);
+
+/******************************************************************************
+ * luat_adc_read
+ * Description: 读取adc通道的值
+ * @param pin[in] adc通道的序号
+ * @param val[out] adc通道的原始值
+ * @param val2[out] adc通道的计算值,与具体通道有关
+ * @return 0 成功, 其他值为失败
+******************************************************************************/
 int luat_adc_read(int pin, int* val, int* val2);
+
+/******************************************************************************
+ * luat_adc_close
+ * Description: 关闭adc通道
+ * @param pin[in] adc通道的序号
+ * @return 0 成功, 其他值为失败
+******************************************************************************/
 int luat_adc_close(int pin);
 
 #endif

luat/include/luat_base.h

@@ -1,54 +1,99 @@
+/******************************************************************************
+ *  LuatOS基础操作
+ *  @author wendal
+ *  @since 0.0.1
+ *****************************************************************************/
 
 #ifndef LUAT_BASE
 #define LUAT_BASE
-
+/**LuatOS版本号*/
 #define LUAT_VERSION "1.0.6-SNAPSHOT"
-
+// 调试开关, 预留
 #define LUAT_DEBUG 0
 
+//-------------------------------
+// 通用头文件
 #include "lua.h"
 #include "lualib.h"
 #include "lauxlib.h"
 #include "stdint.h"
 #include "string.h"
+//-------------------------------
 
 //lua_State * luat_get_state();
+/**
+ * LuatOS主入口函数, 从这里开始就交由LuatOS控制了.
+ * 集成时,该函数应在独立的thread/task中启动
+ */
 int luat_main (int argc, char **argv, int _);
 
+/**
+ * 加载库函数. 平台实现应该根据时间情况, 加载可用的标准库和扩展库.
+ * 其中, 标准库定义为_G/table/io/os等lua原生库.
+ * 扩展库为下述luaopen_XXXX及厂商自行扩展的库.
+ */
 void luat_openlibs(lua_State *L);
 
+// 以下luaopen_大多有平台无关的实现, 需要实现的是对应的luat_XXX_XXX 方法.
 
+/** 加载sys库, 预留, 实际不可用状态*/
 LUAMOD_API int luaopen_sys( lua_State *L );
+/** 加载rtos库, 必选*/
 LUAMOD_API int luaopen_rtos( lua_State *L );
+/** 加载timer库, 可选*/
 LUAMOD_API int luaopen_timer( lua_State *L );
+/** 加载msgbus库, 预留, 实际不可用状态*/
 LUAMOD_API int luaopen_msgbus( lua_State *L );
+/** 加载gpio库, 可选*/
 LUAMOD_API int luaopen_gpio( lua_State *L );
+/** 加载adc库, 可选*/
 LUAMOD_API int luaopen_adc( lua_State *L );
+/** 加载pwm库, 可选*/
 LUAMOD_API int luaopen_pwm( lua_State *L );
+/** 加载uart库, 一般都需要*/
 LUAMOD_API int luaopen_uart( lua_State *L );
+/** 加载pm库, 预留*/
 LUAMOD_API int luaopen_pm( lua_State *L );
+/** 加载fs库, 预留*/
 LUAMOD_API int luaopen_fs( lua_State *L );
+/** 加载wlan库, 操作wifi,可选*/
 LUAMOD_API int luaopen_wlan( lua_State *L );
+/** 加载socket库, 依赖netclient.h,可选*/
 LUAMOD_API int luaopen_socket( lua_State *L );
+/** 加载sensor库, 依赖gpio库, 可选*/
 LUAMOD_API int luaopen_sensor( lua_State *L );
+/** 加载log库, 必选, 依赖底层uart抽象层*/
 LUAMOD_API int luaopen_log( lua_State *L );
+/** 加载json库, 可选*/
 LUAMOD_API int luaopen_cjson( lua_State *L );
+/** 加载i2c库, 可选*/
 LUAMOD_API int luaopen_i2c( lua_State *L );
+/** 加载spi库, 可选*/
+LUAMOD_API int luaopen_spi( lua_State *L );
+/** 加载disp库, 可选, 会依赖i2c和spi*/
 LUAMOD_API int luaopen_disp( lua_State *L );
+/** 加载utest库, 预留*/
 LUAMOD_API int luaopen_utest( lua_State *L );
-LUAMOD_API int luaopen_spi( lua_State *L );
-
+/** 加载mqtt库, 预留*/
 LUAMOD_API int luaopen_mqtt( lua_State *L );
+/** 加载mqtt库, 预留*/
 LUAMOD_API int luaopen_http( lua_State *L );
+/** 加载pack库, 可选,平台无关*/
 LUAMOD_API int luaopen_pack( lua_State *L );
+/** 加载mqttcore库, 可选,平台无关*/
 LUAMOD_API int luaopen_mqttcore( lua_State *L );
 
+/** sprintf需要支持longlong值的打印, 提供平台无关的实现*/
 int l_sprintf(char *buf, size_t size, const char *fmt, ...);
 
+/** 重启设备 */
 void luat_os_reboot(int code);
+/** 设备进入待机模式 */
 void luat_os_standy(int timeout);
+/** 厂商/模块名字, 例如Air302, Air640W*/
 const char* luat_os_bsp(void);
 
+/** 停止启动,当前仅rt-thread实现有这个设置*/
 void stopboot(void);
 
 #endif