improve api docs

zlgopen · Dec 26, 2023 · 3796c88 · 3796c88
1 parent eda88c1
commit 3796c88
Show file tree

Hide file tree

Showing 40 changed files with 93 additions and 93 deletions.
diff --git a/src/awtk_global.h b/src/awtk_global.h
@@ -87,11 +87,11 @@ ret_t tk_quit(void);
  * @alias global_quit_ex
  * @annotation ["static", "scriptable"]
  *
- * @param {uint32_t} delay_ms 延迟退出的时间。
+ * @param {uint32_t} delay 延迟退出的时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
-ret_t tk_quit_ex(uint32_t delay_ms);
+ret_t tk_quit_ex(uint32_t delay);
 
 /**
  * @method tk_get_pointer_x

diff --git a/src/base/timer.h b/src/base/timer.h
@@ -66,7 +66,7 @@ ret_t timer_prepare(timer_get_time_t get_time);
  * @annotation ["scriptable:custom", "static"]
  * @param {timer_func_t} on_timer timer回调函数。
  * @param {void*} ctx timer回调函数的上下文。
- * @param {uint32_t} duration 时间。
+ * @param {uint32_t} duration 时间(毫秒)。
  *
  * @return {uint32_t} 返回timer的ID，TK_INVALID_ID表示失败。
  */
@@ -78,7 +78,7 @@ uint32_t timer_add(timer_func_t on_timer, void* ctx, uint32_t duration);
  * @annotation ["static"]
  * @param {timer_func_t} on_timer timer回调函数，回调函数返回RET_REPEAT，则下次继续执行，否则自动移出。
  * @param {void*} ctx timer回调函数的上下文。
- * @param {uint32_t} duration 时间。
+ * @param {uint32_t} duration 时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -90,7 +90,7 @@ ret_t timer_queue(timer_func_t on_timer, void* ctx, uint32_t duration);
  * @annotation ["static"]
  * @param {timer_func_t} on_timer timer回调函数，回调函数返回RET_REPEAT，则下次继续执行，否则自动移出。
  * @param {void*} ctx timer回调函数的上下文。
- * @param {uint32_t} duration 时间。
+ * @param {uint32_t} duration 时间(毫秒)。
  * @param {tk_destroy_t} on_destroy 回调函数。
  * @param {void*} on_destroy_ctx 回调函数上下文。
  *
@@ -154,7 +154,7 @@ ret_t timer_resume(uint32_t timer_id);
  * 修改指定的timer的duration，修改之后定时器重新开始计时。
  * @annotation ["scriptable", "static"]
  * @param {uint32_t} timer_id timerID。
- * @param {uint32_t} duration 新的时间。
+ * @param {uint32_t} duration 新的时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -200,10 +200,10 @@ uint32_t timer_count(void);
 
 /**
  * @method timer_next_time
- * 返回最近的timer到期时间。
+ * 返回最近的timer到期时间(毫秒)。
  * @annotation ["static"]
  *
- * @return {uint32_t} 返回最近的timer到期时间。
+ * @return {uint32_t} 返回最近的timer到期时间(毫秒)。
  */
 uint32_t timer_next_time(void);
 

diff --git a/src/base/velocity.h b/src/base/velocity.h
@@ -57,7 +57,7 @@ velocity_t* velocity_reset(velocity_t* v);
  * 更新位置。
  *
  * @param {velocity_t*} v velocity对象。
- * @param {uint64_t} time 时间。
+ * @param {uint64_t} time 时间(毫秒)。
  * @param {xy_t} x x坐标。
  * @param {xy_t} y y坐标。
  *

diff --git a/src/base/widget.h b/src/base/widget.h
@@ -2372,7 +2372,7 @@ bool_t widget_equal(widget_t* widget, widget_t* other);
  * 如果定时器的生命周期与控件无关，请直接调用**timer_add**，以避免不必要的内存开销。
  * @param {widget_t*} widget 控件对象。
  * @param {timer_func_t} on_timer timer回调函数。
- * @param {uint32_t} duration_ms 时间。
+ * @param {uint32_t} duration 时间(毫秒)。
  *
  * 使用示例：
  *
@@ -2389,7 +2389,7 @@ bool_t widget_equal(widget_t* widget, widget_t* other);
  *
  * @return {uint32_t} 返回timer的ID，TK_INVALID_ID表示失败。
  */
-uint32_t widget_add_timer(widget_t* widget, timer_func_t on_timer, uint32_t duration_ms);
+uint32_t widget_add_timer(widget_t* widget, timer_func_t on_timer, uint32_t duration);
 
 /**
  * @method widget_remove_timer

diff --git a/src/base/widget_animator.h b/src/base/widget_animator.h
@@ -190,8 +190,8 @@ struct _widget_animator_t {
  * 初始化。仅供子类内部使用。
  * @param {widget_animator_t*} animator 动画对象。
  * @param {widget_t*} widget 控件对象。
- * @param {uint32_t} duration 动画持续时间。
- * @param {uint32_t} delay 动画执行时间。
+ * @param {uint32_t} duration 动画持续时间(毫秒)。
+ * @param {uint32_t} delay 动画执行时间(毫秒)。
  * @param {easing_func_t} easing 插值函数。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

diff --git a/src/base/widget_consts.h b/src/base/widget_consts.h
@@ -585,7 +585,7 @@ BEGIN_C_DECLS
 
 /**
  * @const WIDGET_PROP_AUTO_PLAY
- * 是否自动播放或指定播放的时间。
+ * 是否自动播放或指定播放的时间(毫秒)。
  */
 #define WIDGET_PROP_AUTO_PLAY "auto_play"
 
@@ -759,7 +759,7 @@ BEGIN_C_DECLS
 
 /**
  * @const WIDGET_PROP_LONG_PRESS_TIME
- * 触发长按事件的时间(ms)。
+ * 触发长按事件的时间(毫秒)。
  */
 #define WIDGET_PROP_LONG_PRESS_TIME "long_press_time"
 
@@ -1059,7 +1059,7 @@ BEGIN_C_DECLS
 
 /**
  * @const WIDGET_PROP_ANIMATING_TIME
- * 动画时间。
+ * 动画时间(毫秒)。
  */
 #define WIDGET_PROP_ANIMATING_TIME "animating_time"
 
@@ -1071,7 +1071,7 @@ BEGIN_C_DECLS
 
 /**
  * @const WIDGET_PROP_ANIMATE_ANIMATING_TIME
- * 改变控件属性时附带动画的播放时间。
+ * 改变控件属性时附带动画的播放时间(毫秒)。
  */
 #define WIDGET_PROP_ANIMATE_ANIMATING_TIME "animate:animating_time"
 
@@ -1083,7 +1083,7 @@ BEGIN_C_DECLS
 
 /**
  * @const WIDGET_PROP_SCREEN_SAVER_TIME
- * 屏幕保护时间。
+ * 屏幕保护时间(毫秒)。
  */
 #define WIDGET_PROP_SCREEN_SAVER_TIME "screen_saver_time"
 

diff --git a/src/base/window_manager.h b/src/base/window_manager.h
@@ -354,7 +354,7 @@ ret_t window_manager_set_ignore_input_events(widget_t* widget, bool_t ignore_inp
 
 /**
  * @method window_manager_set_screen_saver_time
- * 设置屏保时间。
+ * 设置屏保时间(毫秒)。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget 窗口管理器对象。
  * @param {uint32_t}  screen_saver_time 屏保时间(单位毫秒), 为0关闭屏保。

diff --git a/src/debugger/debugger.h b/src/debugger/debugger.h
@@ -558,7 +558,7 @@ ret_t debugger_set_current_thread_id(debugger_t* debugger, uint64_t thread_id);
  * @method debugger_dispatch_messages
  * dispatch_messages(仅适用于客户端)
  * @param {debugger_t*} debugger debugger对象。
- * @param {uint32_t} timeout 超时时间。
+ * @param {uint32_t} timeout 超时时间(毫秒)。
  * @param {uint32_t*} ret_num 返回处理命令个数。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

diff --git a/src/ext_widgets/image_animation/image_animation.h b/src/ext_widgets/image_animation/image_animation.h
@@ -196,7 +196,7 @@ ret_t image_animation_set_image(widget_t* widget, const char* image);
 
 /**
  * @method image_animation_set_interval
- * 设置播放间隔时间。
+ * 设置播放间隔时间(毫秒)。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget image_animation对象。
  * @param {uint32_t} interval 间隔时间(毫秒)。

diff --git a/src/ext_widgets/scroll_label/hscroll_label.h b/src/ext_widgets/scroll_label/hscroll_label.h
@@ -94,14 +94,14 @@ typedef struct _hscroll_label_t {
   /**
    * @property {int32_t} lull
    * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
-   * 滚动之间的间歇时间(ms)，缺省3000ms。
+   * 滚动之间的间歇时间(毫秒)，缺省3000ms。
    */
   int32_t lull;
 
   /**
    * @property {int32_t} duration
    * @annotation ["set_prop","get_prop","readable","scriptable"]
-   * 完整的滚动一次需要的时间(ms)，缺省5000ms。
+   * 完整的滚动一次需要的时间(毫秒)，缺省5000ms。
    */
   int32_t duration;
 
@@ -162,7 +162,7 @@ widget_t* hscroll_label_create(widget_t* parent, xy_t x, xy_t y, wh_t w, wh_t h)
  * 设置lull。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget 控件对象。
- * @param {int32_t}  lull 间歇时间(ms)。
+ * @param {int32_t}  lull 间歇时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -173,7 +173,7 @@ ret_t hscroll_label_set_lull(widget_t* widget, int32_t lull);
  * 设置duration。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget 控件对象。
- * @param {int32_t}  duration 滚动时间(ms)。
+ * @param {int32_t}  duration 滚动时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

diff --git a/src/ext_widgets/scroll_view/scroll_bar.h b/src/ext_widgets/scroll_view/scroll_bar.h
@@ -92,7 +92,7 @@ typedef struct _scroll_bar_t {
   /**
    * @property {uint32_t} animator_time
    * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
-   * 翻页滚动动画时间。
+   * 翻页滚动动画时间(毫秒)。
    */
   uint32_t animator_time;
   /**
@@ -197,7 +197,7 @@ ret_t scroll_bar_set_params(widget_t* widget, int32_t virtual_size, int32_t row)
  * @annotation ["scriptable"]
  * @param {widget_t*} widget scroll_bar控件。
  * @param {int32_t} value 值。
- * @param {int32_t} duration 动画持续时间。
+ * @param {int32_t} duration 动画持续时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -273,11 +273,11 @@ bool_t scroll_bar_is_mobile(widget_t* widget);
 
 /**
  * @method scroll_bar_set_animator_time
- * 设置翻页滚动动画时间。
+ * 设置翻页滚动动画时间(毫秒)。
  *
  * @annotation ["scriptable"]
  * @param {widget_t*} widget scroll_bar控件。
- * @param {uint32_t} animator_time 时间。
+ * @param {uint32_t} animator_time 时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -289,8 +289,8 @@ ret_t scroll_bar_set_animator_time(widget_t* widget, uint32_t animator_time);
  *
  * @annotation ["scriptable"]
  * @param {widget_t*} widget scroll_bar控件。
- * @param {int32_t} duration 动画持续时间。
- * @param {int32_t} delay 动画执行时间。
+ * @param {int32_t} duration 动画持续时间(毫秒)。
+ * @param {int32_t} delay 动画执行时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -302,8 +302,8 @@ ret_t scroll_bar_hide_by_opacity_animation(widget_t* widget, int32_t duration, i
  *
  * @annotation ["scriptable"]
  * @param {widget_t*} widget scroll_bar控件。
- * @param {int32_t} duration 动画持续时间。
- * @param {int32_t} delay 动画执行时间。
+ * @param {int32_t} duration 动画持续时间(毫秒)。
+ * @param {int32_t} delay 动画执行时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

diff --git a/src/ext_widgets/scroll_view/scroll_view.h b/src/ext_widgets/scroll_view/scroll_view.h
@@ -351,7 +351,7 @@ ret_t scroll_view_set_slide_limit_ratio(widget_t* widget, float_t slide_limit_ra
  * @param {widget_t*} widget 控件对象。
  * @param {int32_t} xoffset_end x偏移量。
  * @param {int32_t} yoffset_end y偏移量。
- * @param {int32_t} duration 时间。
+ * @param {int32_t} duration 时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -365,7 +365,7 @@ ret_t scroll_view_scroll_to(widget_t* widget, int32_t xoffset_end, int32_t yoffs
  * @param {widget_t*} widget 控件对象。
  * @param {int32_t} xoffset_delta x偏移量。
  * @param {int32_t} yoffset_delta y偏移量。
- * @param {int32_t} duration 时间。
+ * @param {int32_t} duration 时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

diff --git a/src/ext_widgets/serial_widget/serial_widget.h b/src/ext_widgets/serial_widget/serial_widget.h
@@ -227,7 +227,7 @@ ret_t serial_widget_set_flowcontrol(widget_t* widget, uint32_t flowcontrol);
 
 /**
  * @method serial_widget_set_check_interval
- * 设置 轮询时间。
+ * 设置 轮询时间(毫秒)。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget widget对象。
  * @param {uint32_t} check_interval 轮询时间（单位：ms）。

diff --git a/src/ext_widgets/slide_view/slide_view.h b/src/ext_widgets/slide_view/slide_view.h
@@ -89,7 +89,7 @@ typedef struct _slide_view_t {
   /**
    * @property {uint16_t} auto_play
    * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
-   * 自动播放。0表示禁止自动播放，非0表示自动播放时每一页播放的时间。
+   * 自动播放。0表示禁止自动播放，非0表示自动播放时每一页播放的时间(毫秒)。
    */
   uint16_t auto_play;
 
@@ -204,7 +204,7 @@ widget_t* slide_view_cast(widget_t* widget);
  * 设置为自动播放模式。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget slide_view对象。
- * @param {uint16_t} auto_play 0表示禁止自动播放，非0表示自动播放时每一页播放的时间。
+ * @param {uint16_t} auto_play 0表示禁止自动播放，非0表示自动播放时每一页播放的时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
@@ -291,10 +291,10 @@ ret_t slide_view_set_drag_threshold(widget_t* widget, uint32_t drag_threshold);
 
 /**
  * @method slide_view_set_animating_time
- * 设置动画时间。
+ * 设置动画时间(毫秒)。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget slide_view对象。
- * @param {uint32_t} animating_time 动画时间。
+ * @param {uint32_t} animating_time 动画时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

diff --git a/src/ext_widgets/timer_widget/timer_widget.h b/src/ext_widgets/timer_widget/timer_widget.h
@@ -56,7 +56,7 @@ typedef struct _timer_widget_t {
   /**
    * @property {uint32_t} duration
    * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
-   * 时长(ms)。
+   * 时长(毫秒)。
    */
   uint32_t duration;
 
@@ -95,10 +95,10 @@ widget_t* timer_widget_cast(widget_t* widget);
 
 /**
  * @method timer_widget_set_duration
- * 设置 时长(ms)。
+ * 设置 时长(毫秒)。
  * @annotation ["scriptable"]
  * @param {widget_t*} widget widget对象。
- * @param {uint32_t} duration 时长(ms)。
+ * @param {uint32_t} duration 时长(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

diff --git a/src/service/client.h b/src/service/client.h
@@ -101,10 +101,10 @@ ret_t tk_client_read_resp(tk_client_t* client, tk_msg_header_t* header, wbuffer_
  * @method tk_client_read_notify
  * 客户端读取通知。
  * @param {tk_client_t*} client client对象。
- * @param {uint32_t} timeout_ms 超时时间。
+ * @param {uint32_t} timeout 超时时间(毫秒)。
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
-ret_t tk_client_read_notify(tk_client_t* client, uint32_t timeout_ms);
+ret_t tk_client_read_notify(tk_client_t* client, uint32_t timeout);
 
 /**
  * @method tk_client_request

diff --git a/src/streams/misc/ostream_retry.h b/src/streams/misc/ostream_retry.h
@@ -96,7 +96,7 @@ struct _tk_ostream_retry_t {
   /**
    * @property {uint32_t} timeout
    * @annotation ["readable"]
-   * 写超时时间(ms)。
+   * 写超时时间(毫秒)。
    */
   uint32_t timeout;
   /**

diff --git a/src/streams/process/process_helper.h b/src/streams/process/process_helper.h
@@ -127,7 +127,7 @@ int process_handle_get_fd(process_handle_t handle);
  * 等待数据。
  *
  * @param {process_handle_t} handle 子进程句柄。
- * @param {uint32_t} timeout_ms 等待时间(ms)。
+ * @param {uint32_t} timeout_ms 等待时间(毫秒)。
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
 ret_t process_wait_for_data(process_handle_t handle, uint32_t timeout_ms);

diff --git a/src/streams/serial/iostream_serial.h b/src/streams/serial/iostream_serial.h
@@ -110,7 +110,7 @@ ret_t tk_iostream_serial_config(tk_iostream_t* iostream, int32_t baudrate, bytes
  * @method tk_iostream_serial_wait_for_data
  * 等待串口数据。
  * @param {tk_iostream_t*} iostream 串口对象。
- * @param {uint32_t} timeout 等待时间(ms)。
+ * @param {uint32_t} timeout 等待时间(毫秒)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  *

diff --git a/src/streams/shdlc/istream_shdlc.h b/src/streams/shdlc/istream_shdlc.h
@@ -44,7 +44,7 @@ struct _tk_istream_shdlc_t {
 
   /**
    * @property {uint32_t} timeout
-   * 读写超时时间(ms)
+   * 读写超时时间(毫秒)
    */
   uint32_t timeout;
   /**

diff --git a/src/streams/shdlc/ostream_shdlc.h b/src/streams/shdlc/ostream_shdlc.h
@@ -43,7 +43,7 @@ struct _tk_ostream_shdlc_t {
 
   /**
    * @property {uint32_t} timeout
-   * 读写超时时间(ms)
+   * 读写超时时间(毫秒)
    */
   uint32_t timeout;
   /**