Improve documentation in efl_util.h file

Change-Id: Ibb5badfe468f67b11e9e1292c53ded75fb77a49d

diff --git a/include/efl_util.h b/include/efl_util.h
index d104df4f8f4ca6429ea4428455ffaa2a2ffd7366..1a96634917668466dcfdef42de58c3ccdaee6c5c 100644 (file)
--- a/include/efl_util.h
+++ b/include/efl_util.h
@@ -279,9 +279,9 @@ typedef enum
    * @privilege %http://tizen.org/privilege/inputgenerator
    * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
    * @remarks The dev_type is changed into the unsigned int to perform bitwise operations. (Since 3.0)
+   * @remarks The returned object should be released with efl_util_input_deinitialize_generator().
    * @param[in] dev_type The device type want to generate events (ex> #EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN | #EFL_UTIL_INPUT_DEVTYPE_KEYBOARD)
    * @return #efl_util_inputgen_h on success, otherwise @c NULL
-   * @retval #efl_util_inputgen_h The input generator handle
    * @exception #EFL_UTIL_ERROR_NONE Successful
    * @exception #EFL_UTIL_ERROR_PERMISSION_DENIED Has no permission to initialize input generator
    * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
@@ -300,10 +300,10 @@ API efl_util_inputgen_h efl_util_input_initialize_generator(unsigned int dev_typ
    * @privilege %http://tizen.org/privilege/inputgenerator
    * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
    * @remarks The dev_type is changed into the unsigned int to perform bitwise operations.
+   * @remarks The returned object should be released with efl_util_input_deinitialize_generator().
    * @param[in] dev_type The device type want to generate events (ex> #EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN | #EFL_UTIL_INPUT_DEVTYPE_KEYBOARD)
    * @param[in] name The device name (maximum 31 characters)
    * @return #efl_util_inputgen_h on success, otherwise @c NULL
-   * @retval #efl_util_inputgen_h The input generator handle
    * @exception #EFL_UTIL_ERROR_NONE Successful
    * @exception #EFL_UTIL_ERROR_PERMISSION_DENIED Has no permission to initialize input generator
    * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
@@ -328,7 +328,6 @@ API efl_util_inputgen_h efl_util_input_initialize_generator_with_name(unsigned i
    *            Example: #EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN | #EFL_UTIL_INPUT_DEVTYPE_KEYBOARD
    * @param[in] name The device name (maximum 31 characters, can be NULL)
    * @return #efl_util_inputgen_h on success, otherwise @c NULL
-   * @retval #efl_util_inputgen_h The input generator handle
    * @exception #EFL_UTIL_ERROR_NONE Successful
    * @exception #EFL_UTIL_ERROR_PERMISSION_DENIED Has no permission to initialize input generator
    * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
@@ -583,7 +582,7 @@ typedef struct _efl_util_gesture_h * efl_util_gesture_h;
 API extern int EFL_UTIL_EVENT_GESTURE_EDGE_SWIPE;
 
 /**
- * @brief Definition for the edge swipe gesture event.
+ * @brief Definition for the edge drag gesture event.
  * @since_tizen 4.0
  */
 API extern int EFL_UTIL_EVENT_GESTURE_EDGE_DRAG;
@@ -624,7 +623,7 @@ typedef enum _efl_util_gesture_mode_e
 {
    EFL_UTIL_GESTURE_MODE_NONE    = 0, /**< None gesture mode */
    EFL_UTIL_GESTURE_MODE_BEGIN,       /**< Begin a gesture event */
-   EFL_UTIL_GESTURE_MODE_UPDATE,      /**< continually update a gesture event */
+   EFL_UTIL_GESTURE_MODE_UPDATE,      /**< Continually update a gesture event */
    EFL_UTIL_GESTURE_MODE_END,         /**< End a gesture event */
    EFL_UTIL_GESTURE_MODE_DONE         /**< Occur a gesture event */
 } efl_util_gesture_mode_e;
@@ -704,9 +703,9 @@ typedef struct _efl_util_event_gesture_palm_cover_s
 {
    efl_util_gesture_mode_e mode;  /**< Mode of a gesture event */
    unsigned int duration;         /**< Duration time of gesture behavior */
-   int cx;                        /**< Center x point of edge area */
-   int cy;                        /**< Center y point of edge area */
-   unsigned int size;             /**< Size of touched area */
+   int cx;                        /**< Center x point of palm covered area */
+   int cy;                        /**< Center y point of palm covered area */
+   unsigned int size;             /**< Size of palm covered area */
    double pressure;               /**< Pressure of touched finger */
 } efl_util_event_gesture_palm_cover_s;
 
@@ -715,8 +714,8 @@ typedef struct _efl_util_event_gesture_palm_cover_s
  * @since_tizen 4.0
  * @remarks The specific error code can be obtained using the get_last_result() method.
  *          Error codes are described in Exception section.
+ * @remarks The returned object should be released with efl_util_gesture_deinitialize().
  * @return #efl_util_gesture_h on success, otherwise @c NULL
- * @retval #efl_util_gesture_h The global gesture handle
  * @exception #EFL_UTIL_ERROR_NONE Successful
  * @exception #EFL_UTIL_ERROR_NOT_SUPPORTED Not supported
  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
@@ -745,7 +744,6 @@ API int efl_util_gesture_deinitialize(efl_util_gesture_h gesture_h);
  * @param[in] fingers   The number of fingers
  * @param[in] edge      The position of edge
  * @return #efl_util_gesture_data on success, otherwise @c NULL
- * @retval #efl_util_gesture_data The specific gesture data handle
  * @exception #EFL_UTIL_ERROR_NONE Successful
  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
@@ -788,7 +786,6 @@ API int efl_util_gesture_edge_swipe_size_set(efl_util_gesture_data data, efl_uti
  * @param[in] fingers   The number of fingers
  * @param[in] edge      The position of edge
  * @return #efl_util_gesture_data on success, otherwise @c NULL
- * @retval #efl_util_gesture_data The specific gesture data handle
  * @exception #EFL_UTIL_ERROR_NONE Successful
  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
@@ -830,7 +827,6 @@ API int efl_util_gesture_edge_drag_size_set(efl_util_gesture_data data, efl_util
  * @param[in] fingers   The number of fingers
  * @param[in] repeats   The number of repeats
  * @return #efl_util_gesture_data on success, otherwise @c NULL
- * @retval #efl_util_gesture_data The specific gesture data handle
  * @exception #EFL_UTIL_ERROR_NONE Successful
  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
@@ -856,7 +852,6 @@ API int efl_util_gesture_tap_free(efl_util_gesture_h gesture_h, efl_util_gesture
  *          Error codes are described in Exception section.
  * @param[in] gesture_h The #efl_util_gesture_h handle
  * @return #efl_util_gesture_data on success, otherwise @c NULL
- * @retval #efl_util_gesture_data The specific gesture data handle
  * @exception #EFL_UTIL_ERROR_NONE Successful
  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
@@ -972,13 +967,53 @@ API int efl_util_gesture_activate_set(efl_util_gesture_h gesture_h, unsigned int
  */
 API int efl_util_gesture_activate_set_on_window(efl_util_gesture_h gesture_h, Evas_Object *window, unsigned int type, Eina_Bool active);
 
-typedef void (*efl_util_gesture_edge_swipe_cb)(void *data, int mode, int fingers, int sx, int sy, int edge);
-typedef void (*efl_util_gesture_edge_drag_cb)(void *data, int mode, int fingers, int cx, int cy, int edge);
-typedef void (*efl_util_gesture_tap_cb)(void *data, int mode, int fingers, int repeats);
-typedef void (*efl_util_gesture_palm_cover_cb)(void *data, int mode, int duration, int cx, int cy, int size, double pressure);
+/**
+ * @brief Handle for the callback function of edge swipe gesture.
+ * @since_tizen 7.0
+ * @param[in] user_data    The data to be passed to the callback function
+ * @param[in] mode    The mode of a gesture event
+ * @param[in] fingers The number of fingers
+ * @param[in] sx      The start x point of edge area
+ * @param[in] sy      The start y point of edge area
+ * @param[in] edge    The position of edge
+ */
+typedef void (*efl_util_gesture_edge_swipe_cb)(void *user_data, int mode, int fingers, int sx, int sy, int edge);
+
+/**
+ * @brief Handle for the callback function of edge drag gesture.
+ * @since_tizen 7.0
+ * @param[in] user_data    The data to be passed to the callback function
+ * @param[in] mode    The mode of a gesture event
+ * @param[in] fingers The number of fingers
+ * @param[in] cx      The center x point of edge area
+ * @param[in] cy      The center y point of edge area
+ * @param[in] edge    The position of edge
+ */
+typedef void (*efl_util_gesture_edge_drag_cb)(void *user_data, int mode, int fingers, int cx, int cy, int edge);
+/**
+ * @brief Handle for the callback function of tap gesture.
+ * @since_tizen 7.0
+ * @param[in] user_data    The data to be passed to the callback function
+ * @param[in] mode    The mode of a gesture event
+ * @param[in] fingers The number of fingers
+ * @param[in] repeats The number of repeats
+ */
+typedef void (*efl_util_gesture_tap_cb)(void *user_data, int mode, int fingers, int repeats);
+/**
+ * @brief Handle for the callback function of palm cover gesture.
+ * @since_tizen 7.0
+ * @param[in] user_data     The data to be passed to the callback function
+ * @param[in] mode     The mode of a gesture event
+ * @param[in] duration The duration time of gesture behavior
+ * @param[in] cx       The center x point of palm covered area
+ * @param[in] cy       The center y point of palm covered area
+ * @param[in] size     The size of palm covered area
+ * @param[in] pressure The pressure of touched finger
+ */
+typedef void (*efl_util_gesture_palm_cover_cb)(void *user_data, int mode, int duration, int cx, int cy, int size, double pressure);
 
 /**
- * @brief Set edge swipe gesture callback function of given efl util gesture handle.
+ * @brief Sets edge swipe gesture callback function of given efl util gesture handle.
  * @since_tizen 7.0
  * @param[in] gesture_h The #efl_util_gesture_h handle
  * @param[in] cb_func   The callback function pointer
@@ -990,7 +1025,7 @@ typedef void (*efl_util_gesture_palm_cover_cb)(void *data, int mode, int duratio
 API int efl_util_gesture_edge_swipe_cb_set(efl_util_gesture_h gesture_h, efl_util_gesture_edge_swipe_cb cb_func, void *data);
 
 /**
- * @brief Set edge drag gesture callback function of given efl util gesture handle.
+ * @brief Sets edge drag gesture callback function of given efl util gesture handle.
  * @since_tizen 7.0
  * @param[in] gesture_h The #efl_util_gesture_h handle
  * @param[in] cb_func   The callback function pointer
@@ -1002,7 +1037,7 @@ API int efl_util_gesture_edge_swipe_cb_set(efl_util_gesture_h gesture_h, efl_uti
 API int efl_util_gesture_edge_drag_cb_set(efl_util_gesture_h gesture_h, efl_util_gesture_edge_drag_cb cb_func, void *data);
 
 /**
- * @brief Set tap gesture callback function of given efl util gesture handle.
+ * @brief Sets tap gesture callback function of given efl util gesture handle.
  * @since_tizen 7.0
  * @param[in] gesture_h The #efl_util_gesture_h handle
  * @param[in] cb_func   The callback function pointer
@@ -1014,7 +1049,7 @@ API int efl_util_gesture_edge_drag_cb_set(efl_util_gesture_h gesture_h, efl_util
 API int efl_util_gesture_tap_cb_set(efl_util_gesture_h gesture_h, efl_util_gesture_tap_cb cb_func, void *data);
 
 /**
- * @brief Set palm cover gesture callback function of given efl util gesture handle.
+ * @brief Sets palm cover gesture callback function of given efl util gesture handle.
  * @since_tizen 7.0
  * @param[in] gesture_h The #efl_util_gesture_h handle
  * @param[in] cb_func   The callback function pointer