fix api docs

docs/changes.md

@@ -4,6 +4,7 @@
   * fscript公开函数value\_id/value\_func。
   * fscript增加log10/pow10等函数。
   * 修复在多次半透叠加后数据不正常的问题（感谢智明提供补丁）
+  * 修复注释错误(感谢朝泽提供补丁)
 
 2022/01/04
   * fscript支持保存函数名，方便调试。

src/base/assets_manager.h

@@ -271,7 +271,7 @@ asset_info_t* assets_manager_load(assets_manager_t* am, asset_type_t type, const
  * 从文件系统中加载指定的资源，并缓存到内存中。在定义了宏WITH\_FS\_RES时才生效。
  * @param {assets_manager_t*} am asset manager对象。
  * @param {asset_type_t} type 资源的类型。
- * @param {asset_type_t} type 资源的子类型。
+ * @param {uint16_t} subtype 资源的子类型。
  * @param {char*} name 资源的名称。
  *
  * @return {asset_info_t*} 返回资源。

src/base/clip_board.h

@@ -105,7 +105,7 @@ ret_t clip_board_clear(clip_board_t* cl);
  * 设置数据到剪切板中。
  * @param {clip_board_t*} cl 剪切板对象。
  * @param {clip_board_data_type_t} type 数据类型。
- * @param {const void* data} data 数据。
+ * @param {const void*} data 数据。
  * @param {uint32_t} size 数据长度
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -118,7 +118,7 @@ ret_t clip_board_set_data(clip_board_t* cl, clip_board_data_type_t type, const v
  * 从剪切板中获取数据。
  * @param {clip_board_t*} cl 剪切板对象。
  * @param {clip_board_data_type_t*} type 返回数据类型(可为NULL)。
- * @param {void** data} data 返回数据(可为NULL)。
+ * @param {void**} data 返回数据(可为NULL)。
  * @param {uint32_t*} size 返回数据长度(可为NULL)。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

src/base/lcd.h

@@ -704,7 +704,7 @@ ret_t lcd_destroy(lcd_t* lcd);
 ret_t lcd_get_dirty_rect(lcd_t* lcd, rect_t* r);
 
 /**
- * @method lcd_get_dirty_rect
+ * @method lcd_get_dirty_rects
  * 获取 lcd 对象的脏矩形列表。
  * @param {lcd_t*} lcd lcd对象。
  *

src/base/system_info.h

@@ -171,7 +171,7 @@ ret_t system_info_deinit(void);
  * @method system_info_set_font_scale
  * 设置字体缩放比例。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {float_t} font_scale 字体缩放比例。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -182,7 +182,7 @@ ret_t system_info_set_font_scale(system_info_t* info, float_t font_scale);
  * @method system_info_set_app_root
  * 设置app root。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {const char*} app_root app root。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -193,7 +193,7 @@ ret_t system_info_set_app_root(system_info_t* info, const char* app_root);
  * @method system_info_set_default_font
  * 设置缺省字体。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {const char*} default_font 缺省字体。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -204,7 +204,7 @@ ret_t system_info_set_default_font(system_info_t* info, const char* default_font
  * @method system_info_set_lcd_w
  * 设置LCD宽度。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {uint32_t} lcd_w 设置LCD宽度。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -215,7 +215,7 @@ ret_t system_info_set_lcd_w(system_info_t* info, uint32_t lcd_w);
  * @method system_info_set_lcd_h
  * 设置LCD高度。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {uint32_t} lcd_h 设置LCD高度。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -226,7 +226,7 @@ ret_t system_info_set_lcd_h(system_info_t* info, uint32_t lcd_h);
  * @method system_info_set_lcd_type
  * 设置LCD类型。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {lcd_type_t} lcd_type 设置LCD类型。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -237,7 +237,7 @@ ret_t system_info_set_lcd_type(system_info_t* info, lcd_type_t lcd_type);
  * @method system_info_set_lcd_orientation
  * 设置LCD的旋转角度。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {lcd_orientation_t} lcd_orientation 设置LCD的旋转角度。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -248,7 +248,7 @@ ret_t system_info_set_lcd_orientation(system_info_t* info, lcd_orientation_t lcd
  * @method system_info_set_keyboard_type
  * 设置键盘类型。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {keyboard_type_t} keyboard_type 键盘类型。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
@@ -259,7 +259,7 @@ ret_t system_info_set_keyboard_type(system_info_t* info, keyboard_type_t keyboar
  * @method system_info_set_device_pixel_ratio
  * 设置LCD密度。
  *
- * @param {system_info_t* info} info system_info对象。
+ * @param {system_info_t*} info system_info对象。
  * @param {float_t} device_pixel_ratio 设置LCD密度。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。

src/base/text_edit.h

@@ -84,7 +84,7 @@ typedef struct _text_edit_t {
  * @method text_edit_create
  * 创建text_edit对象
  * @param {widget_t*} widget 控件
- * @param {boo_t} single_line 是否是单行编辑器。
+ * @param {bool_t} single_line 是否是单行编辑器。
  *
  * @return {widget_t*} 对象。
  */
@@ -225,7 +225,7 @@ ret_t text_edit_set_cursor(text_edit_t* text_edit, uint32_t cursor);
  * 获取光标位置。
  * @param {text_edit_t*} text_edit text_edit对象。
  *
- * @return {uin32_t} 返回光标的位置。
+ * @return {uint32_t} 返回光标的位置。
  */
 uint32_t text_edit_get_cursor(text_edit_t* text_edit);
 

src/base/vgcanvas_asset_manager.h

@@ -49,7 +49,7 @@ typedef ret_t (*vgcanvas_asset_manager_font_destroy_t)(void* vg, const char* fon
  * @alias vgcanvas_asset_manager_instance
  * @annotation ["constructor", "scriptable"]
  *
- * @return {vgcanvas_asset_manager*} 返回矢量画布资源管理器对象。
+ * @return {vgcanvas_asset_manager_t*} 返回矢量画布资源管理器对象。
  */
 vgcanvas_asset_manager_t* vgcanvas_asset_manager(void);
 

src/base/widget.h

@@ -2521,7 +2521,7 @@ ret_t widget_dispatch_to_key_target(widget_t* widget, event_t* e);
  * @param {xy_t} x x坐标。
  * @param {xy_t} y y坐标。
  *
- * @return {widget*} 子控件或NULL。
+ * @return {widget_t*} 子控件或NULL。
  */
 widget_t* widget_find_target(widget_t* widget, xy_t x, xy_t y);
 

src/base/widget_vtable.h

@@ -44,6 +44,11 @@ ret_t widget_invalidate_default(widget_t* widget, const rect_t* rect);
 /**
  * @method widget_on_event_default
  * @annotation ["global"]
+ *
+ * @param {widget_t*} widget 控件。
+ * @param {event_t*} e 事件对象。
+ *
+ * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */
 ret_t widget_on_event_default(widget_t* widget, event_t* e);
 
@@ -86,7 +91,7 @@ ret_t widget_on_paint_children_clip(widget_t* widget, canvas_t* c);
  * @param {widget_t*} widget 控件对象。
  * @param {rect_t*} clip clip区域(为NULL时使用widget的区域)。
  * @param {canvas_t*} c 画布对象。
- * @param (widget_on_paint_t} on_paint 绘制的回调函数。
+ * @param {widget_on_paint_t} on_paint 绘制的回调函数。
  *
  * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
  */

src/conf_io/app_conf_init.h

@@ -36,7 +36,7 @@ typedef tk_object_t* (*conf_load_t)(const char* url, bool_t create_if_not_exist)
  *
  * @annotation ["global"]
  * 
- * @param {conf_loader_t} load 配置加载函数。
+ * @param {conf_load_t} load 配置加载函数。
  * @param {const char*} app_name 应用程序名称。
  * @param {const char*} extname 文件扩展名。
  * 

src/conf_io/conf_obj.h

@@ -63,7 +63,7 @@ tk_object_t* conf_obj_create(conf_doc_save_t save, conf_doc_load_t load, const c
  * 
  * @param {tk_object_t*} conf conf对象。
  * 
- * @return {conf_dot_t} 返回doc对象。
+ * @return {conf_doc_t*} 返回doc对象。
  * 
  */
 conf_doc_t* conf_obj_get_doc(tk_object_t* conf);

src/dllexports.h

@@ -1,129 +1,142 @@
-? /**
+/**
  * 这个文件单纯用于脚本生成第三方库的导出函数
  *
  */
 
-    /**
+/**
  * @method SDL_ShowCursor
- *
+ * Toggle whether or not the cursor is shown.
  * @annotation ["global"]
- *
+ * @param {int} toggle    1 to show the cursor, 0 to hide it, -1 to query the current state.
+ * @return {int}    1 if the cursor is shown, or 0 if the cursor is hidden.
  */
 
-    /**
+/**
  * @method SDL_WarpMouseInWindow
- *
+ * Moves the mouse to the given position within the window.
  * @annotation ["global"]
- *
+ * @param {SDL_Window*} window    1 to show the cursor, 0 to hide it, -1 to query the current state.
+ * @param {int} x    The x coordinate within the window.
+ * @param {int} y    The y coordinate within the window.
  */
 
-    /**
+/**
  * @method SDL_GetDefaultCursor
- *
+ * Return the default cursor.
  * @annotation ["global"]
- *
+ * @return {SDL_Cursor*}    the default cursor.
  */
 
-    /**
+/**
  * @method SDL_SetCursor
- *
+ * Set the active cursor.
  * @annotation ["global"]
- *
+ * @param {SDL_Cursor*} cursor    cursor.
  */
 
-    /**
+/**
  * @method SDL_FreeCursor
- *
+ * Frees a cursor created with SDL_CreateCursor() or similar functions.
  * @annotation ["global"]
- *
+ * @param {SDL_Cursor*} cursor    cursor.
  */
 
-    /**
+/**
  * @method SDL_CreateSystemCursor
- *
+ * Create a system cursor.
  * @annotation ["global"]
- *
+ * @param {SDL_SystemCursor} id    id.
+ * @return {SDL_Cursor*}    the cursor.
  */
 
-    /**
+/**
  * @method SDL_GetMouseFocus
- *
+ * Get the window which currently has mouse focus.
  * @annotation ["global"]
- *
+ * @return {SDL_Window*}    the window.
  */
 
-    /**
+/**
  * @method SDL_MixAudioFormat
- *
  * @annotation ["global"]
- *
+ * @param {Uint8*} dst
+ * @param {const Uint8*} src
+ * @param {SDL_AudioFormat} format
+ * @param {Uint32} len
+ * @param {int} volume
  */
 
-    /**
+/**
  * @method SDL_DequeueAudio
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev    The device ID from which we will dequeue audio.
+ * @param {void*} data    A pointer into where audio data should be copied.
+ * @param {Uint32} len    The number of bytes (not samples!) to which (data) points.
+ * @return {Uint32}    number of bytes dequeued, which could be less than requested.
  */
 
-    /**
+/**
  * @method SDL_QueueAudio
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev    The device ID to which we will queue audio.
+ * @param {const void*} data    The data to queue to the device for later playback.
+ * @param {Uint32} len    The number of bytes (not samples!) to which (data) points.
+ * @return {Uint32}    0 on success, or -1 on error.
  */
 
-    /**
+/**
  * @method SDL_GetQueuedAudioSize
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev    The device ID of which we will query queued audio size.
+ * @return {Uint32}    Number of bytes (not samples!) of queued audio.
  */
 
-    /**
+/**
  * @method SDL_ClearQueuedAudio
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev    The device ID of which to clear the audio queue.
  */
 
-    /**
+/**
  * @method SDL_PauseAudioDevice
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev
+ * @param {int} pause_on
  */
 
-    /**
+/**
  * @method SDL_CloseAudioDevice
- *
  * @annotation ["global"]
- *
+ * @param {SDL_AudioDeviceID} dev
  */
 
-    /**
+/**
  * @method SDL_OpenAudioDevice
- *
  * @annotation ["global"]
- *
+ * @param {const char*} device
+ * @param {int} iscapture
+ * @param {const SDL_AudioSpec*} desired
+ * @param {const SDL_AudioSpec*} obtained
+ * @param {int} allowed_changes
+ * @return {SDL_AudioDeviceID}    0 on error, a valid device ID that is >= 2 on success.
  */
 
-    /**
+/**
  * @method SDL_WasInit
- *
  * @annotation ["global"]
- *
+ * @param {Uint32} flags
+ * @return {Uint32}
  */
 
-    /**
+/**
  * @method SDL_Init
- *
  * @annotation ["global"]
- *
+ * @param {Uint32} flags
+ * @return {int}
  */
-    /**
+
+/**
  * @method SDL_GetError
- *
  * @annotation ["global"]
- *
+ * @return {const char*}
  */

src/ext_widgets/mledit/line_number.h

@@ -135,7 +135,7 @@ ret_t line_number_set_line_height(widget_t* widget, int32_t line_height);
 ret_t line_number_set_yoffset(widget_t* widget, int32_t yoffset);
 
 /**
- * @method line_number_set_yoffset
+ * @method line_number_set_lines_of_each_row
  * 设置每一个逻辑行(row)占几个物理行(line)。
  * @param {widget_t*} widget 控件对象。
  * @param {const uint32_t*}  lines_of_each_row 每一个逻辑行占几个物理行。

src/hal/network_interface.h

@@ -150,7 +150,7 @@ struct _network_interface_t {
  * 网卡接口创建函数。
  *
  * @param {char *} interface 网卡名。
- * @param {type} network_interface_type_t 网卡接口类型。
+ * @param {network_interface_type_t} type 网卡接口类型。
  *
  * @return {network_interface_t} 网卡接口对象。
  */

src/streams/mem/iostream_mem.h

@@ -52,7 +52,7 @@ struct _tk_iostream_mem_t {
  * @param {void*} buff_in 输入流缓冲区。
  * @param {uint32_t} size_in 输入流缓冲区大小。
  * @param {void*} buff_out 输入流缓冲区。
- * @param {uoutt32_t} size_out 输入流缓冲区大小。
+ * @param {uint32_t} size_out 输入流缓冲区大小。
  * @param {bool_t} own_the_buff 是否让istream对象拥有buff。
  *
  * @return {tk_iostream_t*} 返回iostream对象。

src/svg/bsvg.h

@@ -45,7 +45,7 @@ const uint8_t* bsvg_visit_path(const uint8_t* p, void* ctx, tk_visit_t on_path);
  *
  * @param {bsvg_t*} svg对象。
  * @param {const uint32_t*} data svg数据。
- * @param {size} size data长度。
+ * @param {uint32_t} size data长度。
  *
  * @return {bsvg_t*} 返回解析后的svg。
  */

src/tkc/data_reader_mem.h

@@ -54,7 +54,7 @@ data_reader_t* data_reader_mem_create(const char* memname);
  * 构造内存URL。
  * @annotation ["static"]
  * 
- * @param {mem_t*} mem 内存的地址。
+ * @param {const void*} mem 内存的地址。
  * @param {uint32_t} size 内存的长度。
  * @param {char*} url 生成的URL。
  *

src/tkc/idle_manager.h

@@ -120,7 +120,7 @@ ret_t idle_manager_dispatch(idle_manager_t* idle_manager);
 ret_t idle_manager_remove_all(idle_manager_t* idle_manager);
 
 /**
- * @method idle_manager_remove_all
+ * @method idle_manager_remove_all_by_ctx
  * 根据上下文删除所有符合条件的idle。
  * @param {idle_manager_t*} idle_manager idle_manager_t管理器对象。
  * @param {void*} ctx idle回调函数的上下文。

src/tkc/str.h

@@ -445,7 +445,7 @@ ret_t str_to_float(str_t* str, double* v);
 ret_t str_encode_hex(str_t* str, const uint8_t* data, uint32_t size, const char* format);
 
 /**
- * @method str_encode_hex
+ * @method str_decode_hex
  * 把16进制格式的字符串解码成字符串。
  * @param {str_t*} str str对象。
  * @param {uint8_t*} data 数据缓存区(返回)。