add:添加注释

components/camera/luat_camera.h

@@ -10,6 +10,10 @@
 #ifdef __LUATOS__
 #include "luat_lcd.h"
 #endif
+/**
+ * @defgroup CAMERA  CAMERA设备(CAMERA)
+ * @{
+ */
 enum
 {
 	LUAT_CAMERA_FRAME_START = 0,
@@ -126,4 +130,6 @@ int luat_camera_image_decode_once(uint8_t *data, uint16_t image_w, uint16_t imag
 void luat_camera_image_decode_deinit(void);
 
 int luat_camera_image_decode_get_result(uint8_t *buf);
+
+/** @}*/
 #endif

components/network/libhttp/luat_http.h

@@ -15,7 +15,10 @@
 #define HTTP_RESP_BUFF_SIZE 	(4096)
 
 #endif
-
+/**
+ * @defgroup luatos_HTTP  HTTP(S)相关接口
+ * @{
+ */
 enum
 {
 	HTTP_STATE_IDLE,
@@ -246,5 +249,6 @@ int luat_http_client_pause(luat_http_ctrl_t *http_ctrl, uint8_t is_pause);
  */
 int luat_http_client_set_get_offset(luat_http_ctrl_t *http_ctrl, uint32_t offset);
 // int luat_http_client_start(luat_http_ctrl_t *http_ctrl, const char *url, uint8_t is_post, uint8_t ipv6, uint8_t data_mode);
+/** @}*/
 #endif
 #endif

components/sms/luat_sms.h

@@ -23,7 +23,10 @@
 #define LUAT_SMS_H
 
 #include "luat_base.h"
-
+/**
+ * @defgroup LUAT_SMS  SMS接口
+ * @{
+ */
 #define LUAT_MSG_MAX_ADDR_LEN 80
 #define LUAT_SMS_MAX_TXT_SIZE 640
 #define LUAT_SMS_MAX_PDU_SIZE 180
@@ -106,10 +109,7 @@ typedef struct
     uint8_t seqNum;
 }LUAT_SMS_RECV_MSG_T;
 
-/**
- * @defgroup luatos_sms 短信功能
- * @{
- */
+
 /**
  * @brief 初始化短信
  */
@@ -137,5 +137,5 @@ void luat_sms_recv_msg_register_handler(LUAT_SMS_HANDLE_CB callback_fun);
  * @param callback_fun    回调函数
  */
 void luat_sms_send_msg_register_handler(LUAT_SMS_HANDLE_SEND_CB callback_fun);
-
+/**@}*/
 #endif

luat/include/luat_fota.h

@@ -3,15 +3,39 @@
 
 #include "luat_base.h"
 #include "luat_spi.h"
+/**
+ * @defgroup luatos_fota 远程升级接口
+ * @{
+ */
+
+/**
+ * @brief 用于初始化fota,创建写入升级包数据的上下文结构体
+ * 
+ * @param start_address,开始地址 718/716系列填0
+ * @param  len 长度 718/716系列填0
+ * @param  spi_device 长度 718/716系列填NULL
+ * @param  path 长度 718/716系列填NULL
+ * @param  pathlen 长度 718/716系列填0
+ * @return  
+ */
 
 int luat_fota_init(uint32_t start_address, uint32_t len, luat_spi_device_t* spi_device, const char *path, uint32_t pathlen);
 
+/// @brief 用于向本地 Flash 中写入升级包数据
+/// @param data 升级包数据
+/// @param len 升级包数据长度
+/// @return int =0成功，其他失败
 int luat_fota_write(uint8_t *data, uint32_t len);
 
+/// @brief 用于结束升级包下载
+/// @return int =0成功，其他失败
 int luat_fota_done(void);
 
 int luat_fota_end(uint8_t is_ok);
 
+/// @brief 等待fota 准备，目前没有什么作用
+/// @param  
+/// @return uint8_t =1 准备好
 uint8_t luat_fota_wait_ready(void);
-
+/** @}*/
 #endif

luat/include/luat_fs.h

@@ -11,7 +11,10 @@
 #ifndef LUAT_WEAK
 #define LUAT_WEAK __attribute__((weak))
 #endif
-
+/**
+ * @defgroup luat_fs 文件系统接口
+ * @{
+ */
 typedef struct luat_fs_conf {
     char* busname;
     char* type;
@@ -28,26 +31,123 @@ typedef struct luat_fs_info
     size_t block_size;
 }luat_fs_info_t;
 
-
+/**
+ * @brief 文件系统初始化
+ * @return int =0成功，其他失败
+ */
 int luat_fs_init(void);
 
 int luat_fs_mkfs(luat_fs_conf_t *conf);
 int luat_fs_mount(luat_fs_conf_t *conf);
 int luat_fs_umount(luat_fs_conf_t *conf);
+
+/**
+ * @brief 获取文件系统状态
+ * @param path[IN] 挂载路径, 通常为 /
+ * @param info[OUT] 文件系统信息
+ * @return int =0成功，其他失败
+ */
 int luat_fs_info(const char* path, luat_fs_info_t *conf);
 
+/**
+ * @brief 打开文件,类似于fopen
+ * @param filename[IN] 文件路径
+ * @param mode[IN] 打开模式,与posix类型, 例如 "r" "rw" "w" "w+" "a"
+ * @return FILE* 文件句柄,失败返回NULL
+ */
+
 FILE* luat_fs_fopen(const char *filename, const char *mode);
+
+
+/**
+ * @brief 读到单个字节,类似于getc
+ * @param stream[IN] 文件句柄
+ * @return int >=0读取成功返回, -1失败, 例如读取到文件尾部
+ */
+
 int luat_fs_getc(FILE* stream);
+
+/**
+ * @brief 设置句柄位置,类似于fseek
+ * @param stream[IN] 文件句柄
+ * @param offset[IN] 偏移量
+ * @param origin[IN] 参考点, 例如 SEEK_SET 绝对坐标, SEEK_END 结尾, SEEK_CUR 当前
+ * @return int >=0成功,否则失败
+ */
 int luat_fs_fseek(FILE* stream, long int offset, int origin);
+/**
+ * @brief 获取句柄位置,类似于ftell
+ * @param stream[IN] 文件句柄
+ * @return int >=0当前位置, 否则失败
+ */
 int luat_fs_ftell(FILE* stream);
+
+/**
+ * @brief 关闭句柄位置,类似于fclose
+ * @param stream[IN] 文件句柄
+ * @return int =0成功,否则失败
+ */
 int luat_fs_fclose(FILE* stream);
+/**
+ * @brief 是否已经到文件结尾,类似于feof
+ * @param stream[IN] 文件句柄
+ * @return int =0未到文件尾部,其余为到达文件尾部
+ */
 int luat_fs_feof(FILE* stream);
+/**
+ * @brief 是否有文件系统错误,类似于ferror
+ * @param stream[IN] 文件句柄
+ * @return int =0无错误, 其余为错误值
+ */
 int luat_fs_ferror(FILE *stream);
+/**
+ * @brief 读取文件,类似于fread
+ * @param ptr[OUT] 存放读取数据的缓冲区
+ * @param size[IN] 单次读取大小
+ * @param nmemb[IN] 读取次数
+ * @param stream[IN] 文件句柄
+ * @return int >=0实际读取的数量,<0出错
+ */
 size_t luat_fs_fread(void *ptr, size_t size, size_t nmemb, FILE *stream);
+/**
+ * @brief 写入文件,类似于fwrite
+ * @param ptr[OUT] 存放写入数据的缓冲区
+ * @param size[IN] 单次读取大小
+ * @param nmemb[IN] 读取次数
+ * @param stream[IN] 文件句柄
+ * @return int >=0实际写入的数量,<0出错
+ */
+
 size_t luat_fs_fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);
+
+
+/**
+ * @brief 删除文件,类似于remove
+ * @param filename[IN] 文件路径
+ * @return int =0成功,否则失败
+ */
 int luat_fs_remove(const char *filename);
+/**
+ * @brief 文件改名,类似于rename
+ * @param old_filename[IN] 原文件路径
+ * @param new_filename[IN] 新文件路径
+ * @return int =0成功,否则失败
+ */
+
 int luat_fs_rename(const char *old_filename, const char *new_filename);
+/**
+ * @brief 文件大小,类似于fsize
+ * @param filename[IN] 文件路径
+ * @return int >=0文件大小, 如果文件不存在也是返回0
+ */
+
 size_t luat_fs_fsize(const char *filename);
+
+/**
+ * @brief 文件是否存在,类似于fexist
+ * @param filename[IN] 文件路径
+ * @return int =0不存在,否则存在
+ */
 int luat_fs_fexist(const char *filename);
 int luat_fs_readline(char * buf, int bufsize, FILE * stream);
 void* luat_fs_mmap(FILE * stream);
@@ -57,16 +157,36 @@ void* luat_fs_mmap(FILE * stream);
 
 typedef struct luat_fs_dirent
 {
-    unsigned char d_type;
+    unsigned char d_type; //0:文件；1：文件夹
     char d_name[255];
 }luat_fs_dirent_t;
 
 
+/**
+ * @brief 创建文件夹
+ * @param _DirName[IN] 文件夹路径
+ * @return int =0成功,否则失败
+ */
 int luat_fs_mkdir(char const* _DirName);
+/**
+ * @brief 删除文件夹,必须为空文件夹
+ * @param _DirName[IN] 文件夹路径
+ * @return int =0成功,否则失败
+ */
 int luat_fs_rmdir(char const* _DirName);
-int luat_fs_lsdir(char const* _DirName, luat_fs_dirent_t* ents, size_t offset, size_t len);
 
+/**
+ * @brief 遍历文件夹
+ * @param _DirName[IN] 文件夹路径
+ * @param ents[OUT] 文件列表,必须已分配内存,且不小于len个元素
+ * @param offset[IN] 跳过多少个文件
+ * @param len[IN] 最多读取多少个文件
+ * @return int =>0读取到文件个数,否则失败
+ */
+
+int luat_fs_lsdir(char const* _DirName, luat_fs_dirent_t* ents, size_t offset, size_t len);
 
+/** @}*/
 #ifdef LUAT_USE_FS_VFS
 
 #ifndef LUAT_VFS_FILESYSTEM_MAX

luat/include/luat_pwm.h

@@ -4,23 +4,84 @@
 
 #include "luat_base.h"
 
+/**
+ * @defgroup luatos_device_PWM PWM接口
+ * @{
+*/
+/**
+ * @brief PWM控制参数
+*/
 typedef struct luat_pwm_conf {
-    int channel;
+    int channel; /**<PWM通道 可选通道为 0 / 1 / 2 / 4 总计4个通道*/
     int stop_level;
-    size_t period;
-    size_t pulse;
-    size_t pnum;
-    size_t precision;
+    size_t period;/**<频率, 1Hz - 13MHz*/
+    size_t pulse; /**<占空比，0-100  如将pulse设为50时输出高电平时间占周期50%时间 */
+    size_t pnum; /**<输出周期 0为持续输出, 1为单次输出, 其他为指定脉冲数输出*/
+    size_t precision;/**<分频精度, 100/256/1000, 默认为100, 若设备不支持会有日志提示*/
     uint8_t reverse;
 } luat_pwm_conf_t;
 
 #ifdef __LUATOS__
 #else
+/**
+ * @brief 设置PWM输出完成回调，只有open时，pnum不为0才有回调，必须在pwm open前设置
+ * @param channel: 选择pwm通道 可选通道为 0 / 1 / 2 / 4 总计4个通道
+ *        callback  ：回调函数
+ *        param ：回调时用户参数
+ * @return int
+ */
 int luat_pwm_set_callback(int channel, CBFuncEx_t callback, void *param);
 #endif
+/**
+ * @brief 打开pwm 通道
+ *
+ * @param channel: 选择PWM通道 可选通道为 0 / 1 / 2 / 4 总计4个通道
+ *        period : 设置产生的PWM频率
+ *        pulse  : 设置产生的PWM占空比，单位0.1%
+ *        pnum   ：设置产生的PWM个数，若pnum设为0将一直输出PWM
+ * @return int
+ *         返回值为 0 : 配置PWM成功
+ *         返回值为 -1: PWM通道选择错误
+ *         返回值为 -2: PWM频率设置错误
+ *         返回值为 -3：PWM占空比设置错误
+ *         返回值为 -4: 该PWM通道已被使用
+ */
 int luat_pwm_open(int channel, size_t period, size_t pulse, int pnum);
+/**
+ * @brief 配置pwm 参数
+ *
+ * @param conf->channel: 选择PWM通道 可选通道为 0 / 1 / 2 / 4 总计4个通道
+ *        conf->period : 设置产生的PWM频率
+ *        conf->pulse  : 设置产生的PWM占空比
+ *        conf->pnum   : 设置产生的PWM个数，若pnum设为0将一直输出PWM
+ * @return int
+ *         返回值为 0 : 配置PWM成功
+ *         返回值为 -1: PWM通道选择错误
+ *         返回值为 -2: PWM频率设置错误
+ *         返回值为 -3：PWM占空比设置错误
+ *         返回值为 -4: 该PWM通道已被使用
+ */
 int luat_pwm_setup(luat_pwm_conf_t* conf);
+/**
+ * @brief 获取pwm 频率  本功能暂未实现
+ *
+ * @param id i2c_id
+ * @return int
+ */
 int luat_pwm_capture(int channel,int freq);
+/**
+ * @brief 关闭pwm 接口
+ *
+ * @param channel: 选择PWM通道 可选通道为 0 / 1 / 2 / 4 总计4个通道
+ * @return int
+ */
 int luat_pwm_close(int channel);
+/**
+ * @brief 修改占空比
+ * @param channel: 选择pwm通道 可选通道为 0 / 1 / 2 / 4 总计4个通道
+ *        pulse  ：修改pwm占空比值
+ * @return int
+ */
 int luat_pwm_update_dutycycle(int channel, size_t pulse);
+/** @}*/
 #endif

luat/include/luat_rtc.h

@@ -2,9 +2,26 @@
 #define LUAT_RTC_H
 #include "luat_base.h"
 #include "time.h"
+/**
+ * @defgroup luatos_RTC  时钟接口(RTC)
+ * @{
+ */
 
+/**
+ * @brief 设置系统时间
+ * 
+ * @param tblock 
+ * @return int =0成功，其他失败
+ */
 int luat_rtc_set(struct tm *tblock);
+/**
+ * @brief 获取系统时间
+ * 
+ * @param tblock 
+ * @return int =0成功，其他失败
+ */
 int luat_rtc_get(struct tm *tblock);
+/** @}*/
 int luat_rtc_timer_start(int id, struct tm *tblock);
 int luat_rtc_timer_stop(int id);
 void luat_rtc_set_tamp32(uint32_t tamp);

luat/include/luat_spi.h

@@ -2,19 +2,21 @@
 #ifndef LUAT_SPI_H
 #define LUAT_SPI_H
 #include "luat_base.h"
-
+/**
+ * @defgroup luatos_device_spi SPI接口
+ * @{
+*/
 typedef struct luat_spi
 {
-    /* data */
-    int  id;      // id
-    int  CPHA;    // CPHA
-    int  CPOL;    // CPOL
-    int  dataw;   // 数据宽度
-    int  bit_dict;// 高低位顺序    可选，默认高位在前
-    int  master;  // 主模式     可选，默认主
-    int  mode;    // 全双工       可选，默认全双工
-    int bandrate;// 最大频率20M
-    int cs;      // cs控制引脚
+    int  id;            /**< spi id        可选  1，0*/
+    int  CPHA;          /**< CPHA          可选  1，0*/  
+    int  CPOL;          /**< CPOL          可选  1，0*/  
+    int  dataw;         /**< 数据宽度        8：8bit */
+    int  bit_dict;      /**< 高低位顺序     可选  1：MSB，   0：LSB     */  
+    int  master;        /**< 设置主从模式   可选  1：主机，  0：从机     */  
+    int  mode;          /**< 设置全\半双工  可选  1：全双工，0：半双工    */  
+    int bandrate;       /**< 频率           最小100000， 最大25600000*/  
+    int cs;             /**< cs控制引脚     SPI0的片选为GPIO8, 当配置为8时，表示启用SPI0自带片选；其他配置时，需要自行编码控制片选*/  
 } luat_spi_t;
 
 typedef struct luat_spi_device
@@ -46,19 +48,50 @@ typedef struct luat_fatfs_spi
     spi.master,--主模式     可选，默认主
     spi.full,--全双工       可选，默认全双工
 */
-
-//初始化配置SPI各项参数，并打开SPI
-//成功返回0
+/**
+ * @brief 初始化配置SPI各项参数，并打开SPI
+ * 
+ * @param spi spi结构体
+ * @return int 成功返回0
+ */
 int luat_spi_setup(luat_spi_t* spi);
 //收发SPI数据尝试启动DMA模式
 int luat_spi_config_dma(int spi_id, uint32_t tx_channel, uint32_t rx_channel);
-//关闭SPI，成功返回0
+/**
+ * @brief 关闭SPI
+ * 
+ * @param spi_id spi id
+ * @return int 成功返回0
+ */
 int luat_spi_close(int spi_id);
-//收发SPI数据，返回接收字节数
+/**
+ * @brief 收发SPI数据
+ * 
+ * @param spi_id spi id
+ * @param send_buf 发送数据
+ * @param send_length 发送数据长度
+ * @param recv_buf 接收数据
+ * @param recv_length 接收数据长度
+ * @return int 返回接收字节数
+ */
 int luat_spi_transfer(int spi_id, const char* send_buf, size_t send_length, char* recv_buf, size_t recv_length);
-//收SPI数据，返回接收字节数
+/**
+ * @brief 收SPI数据
+ * 
+ * @param spi_id spi id
+ * @param recv_buf 接收数据
+ * @param length 数据长度
+ * @return int 返回接收字节数
+ */
 int luat_spi_recv(int spi_id, char* recv_buf, size_t length);
-//发SPI数据，返回发送字节数
+/**
+ * @brief 发SPI数据
+ * 
+ * @param spi_id spi id
+ * @param send_buf 发送数据
+ * @param length 数据长度
+ * @return int 返回发送字节数
+ */
 int luat_spi_send(int spi_id, const char* send_buf, size_t length);
 
 int luat_spi_change_speed(int spi_id, uint32_t speed);
@@ -79,5 +112,5 @@ int luat_spi_device_transfer(luat_spi_device_t* spi_dev, const char* send_buf, s
 int luat_spi_device_recv(luat_spi_device_t* spi_dev, char* recv_buf, size_t length);
 //发SPI数据，返回发送字节数
 int luat_spi_device_send(luat_spi_device_t* spi_dev, const char* send_buf, size_t length);
-
+/**@}*/
 #endif