improve api comment and export some functions

docs/changes.md

@@ -1,5 +1,8 @@
 # 最新动态
 
+2024/04/20
+  * 完善注释，导出部分函数。
+
 2024/04/19
   * 增加函数str\_shrink/wstr\_shrink。
   * 修复mledit初始化时，最大行数小于实际行数会崩溃的问题(感谢培煌发现问题)。

src/base/input_device_status.h

@@ -159,7 +159,6 @@ ret_t input_device_status_on_pointer_leave(input_device_status_t* ids, widget_t*
 /**
  * @method input_device_status_deinit
  * 销毁输入设备状态管理器。
- * @annotation ["destructor"]
  * @param {input_device_status_t*} ids 输入设备状态管理器对象。
  * 
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

src/base/main_loop.h

@@ -77,12 +77,69 @@ main_loop_t* main_loop_init(int w, int h);
  */
 main_loop_t* main_loop(void);
 
+/**
+ * @method main_loop_set
+ * 设置当前main_loop对象
+ * @param {main_loop_t*} loop main_loop对象。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_set(main_loop_t* loop);
+
+/**
+ * @method main_loop_run
+ * 运行主循环。
+ * @param {main_loop_t*} l main_loop对象。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_run(main_loop_t* l);
+
+/**
+ * @method main_loop_wakeup
+ * 唤醒主循环。
+ * @param {main_loop_t*} l main_loop对象。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_wakeup(main_loop_t* l);
+
+/**
+ * @method main_loop_quit
+ * 退出主循环。
+ * @param {main_loop_t*} l main_loop对象。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_quit(main_loop_t* l);
+
+/**
+ * @method main_loop_queue_event
+ * 将事件加入到事件队列。
+ * @param {main_loop_t*} l main_loop对象。
+ * @param {const event_queue_req_t*} e 事件。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_queue_event(main_loop_t* l, const event_queue_req_t* e);
+
+/**
+ * @method main_loop_recv_event
+ * 从事件队列中获取事件。
+ * @param {main_loop_t*} l main_loop对象。
+ * @param {event_queue_req_t*} r 事件。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_recv_event(main_loop_t* l, event_queue_req_t* r);
+
+/**
+ * @method main_loop_destroy
+ * 销毁main_loop对象。
+ * @param {main_loop_t*} l main_loop对象。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_destroy(main_loop_t* l);
 
 /**

src/base/native_window.h

@@ -267,9 +267,42 @@ typedef native_window_t* (*native_window_create_t)(widget_t* widget);
  */
 ret_t native_window_invalidate(native_window_t* win, const rect_t* r);
 
+/**
+ * @method native_window_swap_buffer
+ * 交换缓冲区。
+ * @param {native_window_t*} win win对象。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t native_window_swap_buffer(native_window_t* win);
+
+/**
+ * @method native_window_gl_make_current
+ * 设置当前的opengl上下文。
+ * @param {native_window_t*} win win对象。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t native_window_gl_make_current(native_window_t* win);
+
+/**
+ * @method native_window_preprocess_event
+ * 预处理事件。
+ * @param {native_window_t*} win win对象。
+ * @param {event_t*} e 事件。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t native_window_preprocess_event(native_window_t* win, event_t* e);
+
+/**
+ * @method native_window_get_info
+ * 获取窗口信息。
+ * @param {native_window_t*} win win对象。
+ * @param {native_window_info_t*} info 窗口信息。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t native_window_get_info(native_window_t* win, native_window_info_t* info);
 
 /*public for window manager only*/

src/base/system_info.h

@@ -334,8 +334,25 @@ ret_t system_info_set_app_info(system_info_t* info, app_type_t app_type, const c
 ret_t system_info_eval_exprs(system_info_t* info, const char* exprs, tk_visit_t on_expr_result,
                              void* ctx);
 
+/**
+ * @method system_info_set_app_name
+ * 设置应用程序的名称。
+ * @annotation ["static"]
+ * @param {system_info_t*} info system_info对象。
+ * @param {const char*} app_name 应用程序的名称。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t system_info_set_app_name(system_info_t* info, const char* app_name);
 
+/**
+ * @method tk_is_swap_size_by_orientation
+ * 根据旧的和新的方向判断是否需要交换宽度和高度。
+ * @annotation ["static"]
+ * @param {lcd_orientation_t} old_orientation 旧的方向。
+ * @param {lcd_orientation_t} new_orientation 新的方向。
+ * @return {bool_t} 返回是否需要交换宽度和高度。
+*/
 bool_t tk_is_swap_size_by_orientation(lcd_orientation_t old_orientation,
                                       lcd_orientation_t new_orientation);
 

src/base/window_manager.h

@@ -302,7 +302,6 @@ ret_t window_manager_paint(widget_t* widget);
  *
  *> 仅由主循环调用。
  *
- * @annotation ["private"]
  * @param {widget_t*} widget 窗口管理器对象。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

src/main_loop/main_loop_simple.h

@@ -32,6 +32,11 @@
 
 BEGIN_C_DECLS
 
+/**
+ * @class main_loop_simple_t
+ * @parent main_loop_t
+ * 简单的主循环。
+ */
 struct _main_loop_simple_t;
 typedef struct _main_loop_simple_t main_loop_simple_t;
 
@@ -57,12 +62,60 @@ struct _main_loop_simple_t {
   main_loop_dispatch_input_t dispatch_input;
 };
 
+/**
+ * @method main_loop_simple_init
+ * 初始化main_loop_simple_t对象。
+ * @param {int} w 宽度。
+ * @param {int} h 高度。
+ * @param {main_loop_queue_event_t} queue_event 队列事件处理函数。
+ * @param {main_loop_recv_event_t} recv_event 接收事件处理函数。
+ *
+ * @return {main_loop_simple_t*} 返回main_loop_simple_t对象。
+ */
 main_loop_simple_t* main_loop_simple_init(int w, int h, main_loop_queue_event_t queue_event,
                                           main_loop_recv_event_t recv_event);
 
+/**
+ * @method main_loop_simple_reset
+ * 销毁main_loop_simple_t对象。
+ * @param {main_loop_simple_t*} loop main_loop_simple_t对象。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_simple_reset(main_loop_simple_t* loop);
+
+/**
+ * @method main_loop_post_key_event
+ * 发送按键事件。
+ * @param {main_loop_t*} l 主循环对象。
+ * @param {bool_t} pressed 是否按下。
+ * @param {uint8_t} key 按键。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ 
+*/
 ret_t main_loop_post_key_event(main_loop_t* l, bool_t pressed, uint8_t key);
+
+/**
+ * @method main_loop_post_pointer_event
+ * 发送指针事件。
+ * @param {main_loop_t*} l 主循环对象。
+ * @param {bool_t} pressed 是否按下。
+ * @param {xy_t} x x坐标。
+ * @param {xy_t} y y坐标。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_post_pointer_event(main_loop_t* l, bool_t pressed, xy_t x, xy_t y);
+
+/**
+ * @method main_loop_post_multi_gesture_event
+ * 发送多点触控事件。
+ * @param {main_loop_t*} l 主循环对象。
+ * @param {multi_gesture_event_t*} event 事件。
+ * 
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
+ */
 ret_t main_loop_post_multi_gesture_event(main_loop_t* l, multi_gesture_event_t* event);
 
 #ifndef MAIN_LOOP_QUEUE_SIZE