From: Jihoon Kim <jihoon48.kim@samsung.com>
Date: Thu, 18 Apr 2019 10:35:43 +0000 (+0900)
Subject: Fix descriptions detected by check header script
X-Git-Tag: submit/tizen/20190705.053302~2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a75a3fce7128bd1b424d355711b875953cbb2907;p=platform%2Fcore%2Fapi%2Finputmethod.git

Fix descriptions detected by check header script

Change-Id: Iad3e24c63b070d063a0f5f293ecbb769130e05b0
Signed-off-by: Jihoon Kim <jihoon48.kim@samsung.com>
---

diff --git a/include/inputmethod.h b/include/inputmethod.h
index b6b10d9..8e94af9 100644
--- a/include/inputmethod.h
+++ b/include/inputmethod.h
@@ -237,6 +237,7 @@ typedef void (*ime_terminate_cb)(void *user_data);
  * @remarks This callback function is mandatory and must be registered using ime_run().
  * IME application should configure its input panel with #ime_context_h structure information.
  * The ime_get_main_window() can be used to get the created input panel window.
+ * @a context should not be released.
  *
  * @param[in] context_id The input context identification value of an associated text input UI control
  * @param[in] context The input context information handle
@@ -324,6 +325,7 @@ typedef void (*ime_focus_out_cb)(int context_id, void *user_data);
  * @privilege %http://tizen.org/privilege/ime
  *
  * @remarks The ime_request_surrounding_text() must be called to invoke this callback function, asynchronously.
+ * @remarks @a text can be used only in the callback. To use outside, make a copy.
  *
  * @param[in] context_id The input context identification value of an associated text input UI control
  * @param[in] text The UTF-8 string requested
@@ -417,7 +419,7 @@ typedef void (*ime_language_set_cb)(Ecore_IMF_Input_Panel_Lang language, void *u
 /**
  * @brief Called to set the application specific data to deliver to the input panel.
  *
- * @details This API is used by the applications to deliver the specific data to the input panel.
+ * @details This function is used by the applications to deliver the specific data to the input panel.
  * The data format MUST be negotiated by both application and input panel.
  *
  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
@@ -426,6 +428,8 @@ typedef void (*ime_language_set_cb)(Ecore_IMF_Input_Panel_Lang language, void *u
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks @data should not be released.
+ *
  * @param[in] data The specific data to be set to the input panel
  * @param[in] data_length The length of data, in bytes, to send to the input panel
  * @param[in] user_data User data to be passed from the callback registration function
@@ -448,7 +452,7 @@ typedef void (*ime_imdata_set_cb)(void *data, unsigned int data_length, void *us
  *
  * @privilege %http://tizen.org/privilege/ime
  *
- * @remarks The allocated @a data will be released internally.
+ * @remarks The allocated @a data and @a data_length will be released internally.
  *
  * @param[in] user_data User data to be passed from the callback registration function
  * @param[out] data Input panel's data to be set to the application
@@ -539,6 +543,8 @@ typedef void (*ime_return_key_state_set_cb)(bool disabled, void *user_data);
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks @a x, @a y, @a w, and @a h should not be released.
+ *
  * @param[in] user_data User data to be passed from the callback registration function
  * @param[out] x The x position in screen
  * @param[out] y The y position in screen
@@ -688,6 +694,7 @@ typedef void (*ime_accessibility_state_changed_cb)(bool state, void *user_data);
  *
  * @remarks if Input panel requests to open the option window, @a type will be #IME_OPTION_WINDOW_TYPE_KEYBOARD.
  * And if Settings application requests to open it, @a type will be #IME_OPTION_WINDOW_TYPE_SETTING_APPLICATION.
+ * The @a window should not be released. The @a window can be used until ime_option_window_destroyed_cb() will be called.
  *
  * @param[in] window The created window object
  * @param[in] type The type of option window
@@ -710,6 +717,8 @@ typedef void (*ime_option_window_created_cb)(Evas_Object *window, ime_option_win
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks The @a window should be released using evas_object_del().
+ *
  * @param[in] window The window object to destroy
  * @param[in] user_data User data to be passed to the callback function
  *
@@ -1562,6 +1571,7 @@ int ime_send_key_event(ime_key_code_e keycode, ime_key_mask_e keymask, bool forw
  *
  * @return 0 on success, otherwise a negative error value
  * @retval #IME_ERROR_NONE No error
+ * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
  *
@@ -1796,7 +1806,7 @@ int ime_set_selection(int start, int end);
 int ime_get_selected_text(char **text);
 
 /**
- * @brief This API returns the pointer of input panel main window.
+ * @brief Gets the pointer of input panel main window.
  *
  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
  *
@@ -1805,6 +1815,7 @@ int ime_get_selected_text(char **text);
  * @privilege %http://tizen.org/privilege/ime
  *
  * @remarks The specific error code can be obtained using the get_last_result() method if this function returns NULL.
+ * @remarks The returned value should not be released. The returned value is managed by the platform and will be released when terminating this process.
  *
  * @return The input panel main window object on success, otherwise NULL
  *
@@ -1822,7 +1833,7 @@ int ime_get_selected_text(char **text);
 Evas_Object* ime_get_main_window(void);
 
 /**
- * @brief This API updates the input panel window's size information.
+ * @brief Updates the input panel window's size information.
  *
  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
  *
@@ -1837,6 +1848,7 @@ Evas_Object* ime_get_main_window(void);
  *
  * @return 0 on success, otherwise a negative error value
  * @retval #IME_ERROR_NONE No error
+ * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
  *
diff --git a/include/inputmethod_device_event.h b/include/inputmethod_device_event.h
index ec1352f..8ecbd10 100644
--- a/include/inputmethod_device_event.h
+++ b/include/inputmethod_device_event.h
@@ -32,7 +32,7 @@ extern "C" {
  */
 
  /**
- * @brief The handle to retrieve unconventional input device specific event data
+ * @brief The handle to retrieve unconventional input device specific event data.
  *
  * @since_tizen @if WEARABLE 3.0 @endif
  *
@@ -41,7 +41,7 @@ extern "C" {
 typedef void *ime_input_device_event_h;
 
 /**
- * @brief Enumeration of unconventional input devices
+ * @brief Enumeration of unconventional input devices.
  *
  * @since_tizen @if WEARABLE 3.0 @endif
  *
@@ -53,7 +53,7 @@ typedef enum {
 } ime_input_device_type_e;
 
 /**
- * @brief Enumeration of directions for rotary input device's rotation event
+ * @brief Enumeration of directions for rotary input device's rotation event.
  *
  * @since_tizen @if WEARABLE 3.0 @endif
  *
@@ -70,10 +70,11 @@ typedef enum
  *
  * @details This function processes the input event before an associated text input UI control does.
  *
+ * @since_tizen @if WEARABLE 3.0 @endif
+ *
  * @remarks @a device_type contains the information what kind of unconventional input device generated the given event,
  * and the handle @a device_event is used for obtaining device-specific input device event data.
- *
- * @since_tizen @if WEARABLE 3.0 @endif
+ * @a device_event should not be released.
  *
  * @param[in] device_type The unconventional input device type
  * @param[in] device_event The handle for device_type specific input device event
@@ -88,15 +89,15 @@ typedef void(*ime_process_input_device_event_cb)(ime_input_device_type_e device_
 /**
  * @brief Sets @c process_input_device_event event callback function.
  *
- * @remarks The ime_process_input_device_event_cb() callback function is called when the event
- * is received from unconventional input devices that needs to be handled by IMEs.
- *
  * @since_tizen @if WEARABLE 3.0 @endif
  *
  * @privlevel public
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks The ime_process_input_device_event_cb() callback function is called when the event
+ * is received from unconventional input devices that needs to be handled by IMEs.
+ *
  * @param[in] callback_func @c inputmethod_process_input_device_event_cb callback function
  * @param[in] user_data User data to be passed to the callback function
  *
@@ -146,15 +147,15 @@ int ime_event_set_process_input_device_event_cb(ime_process_input_device_event_c
 /**
  * @brief Unsets @c process_input_device_event event callback function.
  *
- * @remarks The ime_process_input_device_event_cb() callback function is called when the event
- * is received from unconventional input devices that needs to be handled by IMEs.
- *
  * @since_tizen @if WEARABLE 3.0 @endif
  *
  * @privlevel public
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks The ime_process_input_device_event_cb() callback function is called when the event
+ * is received from unconventional input devices that needs to be handled by IMEs.
+ *
  * @return 0 on success, otherwise a negative error value
  * @retval #IME_ERROR_NONE No error
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
@@ -168,8 +169,8 @@ int ime_event_unset_process_input_device_event_cb(void);
 /**
  * @brief Gets the direction of the rotary input device event
  *
- * If the device_type parameter of the ime_process_input_device_event_cb function indicates
- * the current input device type is IME_INPUT_DEVICE_TYPE_ROTARY, then the device_event parameter
+ * If the device_type parameter of the ime_process_input_device_event_cb() function indicates
+ * the current input device type is #IME_INPUT_DEVICE_TYPE_ROTARY, then the device_event parameter
  * can be used to retrieve rotary device specific parameters, such as direction, as shown in the sample code.
  *
  * @since_tizen @if WEARABLE 3.0 @endif
@@ -212,4 +213,4 @@ int ime_input_device_rotary_get_direction(ime_input_device_event_h event_handle,
  * @}
  */
 
-#endif /* __TIZEN_UIX_INPUTMETHOD_EVTDEF_H__ */
+#endif /* __TIZEN_UIX_INPUTMETHOD_DEVICE_EVENT_H__ */
diff --git a/include/inputmethod_internal.h b/include/inputmethod_internal.h
index e21b103..5e40eb4 100644
--- a/include/inputmethod_internal.h
+++ b/include/inputmethod_internal.h
@@ -30,7 +30,7 @@ extern "C" {
 #endif
 
 /**
- * @brief Enumeration for input method optimization hint
+ * @brief Enumeration for input method optimization hint.
  *
  * @since_tizen 5.0
  */
@@ -84,33 +84,36 @@ typedef void (*ime_candidate_hide_cb)(int context_id, void *user_data);
  *
  * @privilege %http://tizen.org/privilege/ime
  *
+ * @remarks @a list should not be released.
+ *
  * @param[in] list candidate list
  * @param[in] user_data User data to be passed from the callback registration function
  */
 typedef void (*ime_lookup_table_changed_cb)(Eina_List *list, void *user_data);
 
 /**
- * @brief Called when a optimization hint value is set
+ * @brief Called when a optimization hint value is set.
  *
  * @since_tizen 5.0
  *
  * @privilege %http://tizen.org/privilege/ime
  *
  * @param[in] hint The hint value used for optimization
+ * @param[in] user_data User data to be passed from the callback registration function
  */
 typedef void (*ime_optimization_hint_set_cb)(ime_optimization_hint_e hint, void *user_data);
 
 /**
- * @brief Sets @c ime_caps_mode_changed_cb event callback function.
+ * @brief Sets @c ime_caps_mode_changed_cb() event callback function.
  *
  * @since_tizen 3.0
  *
  * @privilege %http://tizen.org/privilege/ime
  *
- * @remarks The ime_caps_mode_changed_cb () callback function is called when an associated text input
+ * @remarks The ime_caps_mode_changed_cb() callback function is called when an associated text input
  * UI control sends the change of caps mode.
  *
- * @param[in] callback_func @c ime_caps_mode_changed_cb event callback function
+ * @param[in] callback_func @c ime_caps_mode_changed_cb() event callback function
  * @param[in] user_data User data to be passed to the callback function
  *
  * @return 0 on success, otherwise a negative error value
@@ -126,16 +129,13 @@ typedef void (*ime_optimization_hint_set_cb)(ime_optimization_hint_e hint, void
 int ime_event_set_caps_mode_changed_cb(ime_caps_mode_changed_cb callback_func, void *user_data);
 
 /**
- * @brief Sets @c ime_caps_mode_changed_cb event callback function.
+ * @brief Sets @c ime_candidate_show_cb() event callback function.
  *
  * @since_tizen 3.0
  *
  * @privilege %http://tizen.org/privilege/ime
  *
- * @remarks The ime_caps_mode_changed_cb () callback function is called when an associated text input
- * UI control sends the change of caps mode.
- *
- * @param[in] callback_func @c ime_caps_mode_changed_cb event callback function
+ * @param[in] callback_func @c ime_candidate_show_cb() event callback function
  * @param[in] user_data User data to be passed to the callback function
  *
  * @return 0 on success, otherwise a negative error value
@@ -153,7 +153,7 @@ int ime_event_set_candidate_show_cb(ime_candidate_show_cb callback_func, void *u
 int ime_event_set_candidate_hide_cb(ime_candidate_hide_cb callback_func, void *user_data);
 
 /**
- * @brief Sets @c ime_lookup_table_changed_cb event callback function.
+ * @brief Sets @c ime_lookup_table_changed_cb() event callback function.
  *
  * @since_tizen 3.0
  *
@@ -162,7 +162,7 @@ int ime_event_set_candidate_hide_cb(ime_candidate_hide_cb callback_func, void *u
  * @remarks The ime_lookup_table_changed_cb() callback function is called when an associated text input
  * UI control sends the change of caps mode.
  *
- * @param[in] callback_func @c ime_lookup_table_changed_cb event callback function
+ * @param[in] callback_func @c ime_lookup_table_changed_cb() event callback function
  * @param[in] user_data User data to be passed to the callback function
  *
  * @return 0 on success, otherwise a negative error value
@@ -204,7 +204,7 @@ int ime_event_set_lookup_table_changed_cb(ime_lookup_table_changed_cb callback_f
 int ime_context_get_caps_mode(ime_context_h context, bool *caps_mode);
 
 /**
- * @brief Set keyboard engine.
+ * @brief Sets keyboard engine.
  *
  * @since_tizen 3.0
  *
@@ -221,7 +221,7 @@ int ime_context_get_caps_mode(ime_context_h context, bool *caps_mode);
 int ime_set_imengine(const char *engine_id);
 
 /**
- * @brief Flush state in Input Method engine.
+ * @brief Flushes state in Input Method engine.
  *
  * @since_tizen 3.0
  *
@@ -232,10 +232,10 @@ int ime_set_imengine(const char *engine_id);
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
  */
-int ime_flush_imengine();
+int ime_flush_imengine(void);
 
 /**
- * @brief Reset state in Input Method engine.
+ * @brief Resets state in Input Method engine.
  *
  * @since_tizen 3.0
  *
@@ -246,10 +246,10 @@ int ime_flush_imengine();
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
  */
-int ime_reset_imengine();
+int ime_reset_imengine(void);
 
 /**
- * @brief Send the selected item index in the candidate list.
+ * @brief Sends the selected item index in the candidate list.
  *
  * @since_tizen 3.0
  *
@@ -265,7 +265,7 @@ int ime_reset_imengine();
 int ime_select_candidate(unsigned int index);
 
 /**
- * @brief Send the input context event.
+ * @brief Sends the input context event.
  *
  * @since_tizen 3.0
  *
@@ -282,7 +282,7 @@ int ime_select_candidate(unsigned int index);
 int ime_update_input_context(unsigned int type, unsigned int value);
 
 /**
- * @brief Explicitly request IME to initialize
+ * @brief Requests IME to initialize explicitly.
  *
  * @details When using ime_run API, the initialize / prepare / finalize procedures
  * are processed automatically inside the IME application loop.
@@ -297,10 +297,10 @@ int ime_update_input_context(unsigned int type, unsigned int value);
  * @retval #IME_ERROR_NONE No error
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  */
-int ime_initialize();
+int ime_initialize(void);
 
 /**
- * @brief Request IME to prepare resources such as IME window and socket connection
+ * @brief Requests IME to prepare resources such as IME window and socket connection.
  *
  * @details Like ime_initialize() function, this procedure is automatically processed
  * when using ime_run() API. Call this function only when ime_run() is not used and
@@ -315,10 +315,10 @@ int ime_initialize();
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
  */
-int ime_prepare();
+int ime_prepare(void);
 
 /**
- * @brief Explicitly request IME to finalize
+ * @brief Requests IME to finalize explicitly.
  *
  * @since_tizen 4.0
  *
@@ -328,10 +328,10 @@ int ime_prepare();
  * @retval #IME_ERROR_NONE No error
  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
  */
-int ime_finalize();
+int ime_finalize(void);
 
 /**
- * @brief Set flag whether IME is called from dotnet
+ * @brief Sets flag whether IME is called from dotnet.
  *
  * @since_tizen 4.0
  *
@@ -345,7 +345,7 @@ int ime_finalize();
 int ime_set_dotnet_flag(bool set);
 
 /**
- * @brief Set flag whether creating IME window should be defered until there is a access request
+ * @brief Sets flag whether creating IME window should be defered until there is a access request.
  *
  * @since_tizen 5.0
  *
@@ -359,7 +359,7 @@ int ime_set_dotnet_flag(bool set);
 int ime_set_window_creation_defer_flag(bool flag);
 
 /**
- * @brief Sets @c ime_optimization_hint_set_cb event callback function.
+ * @brief Sets @c ime_optimization_hint_set_cb() event callback function.
  *
  * @since_tizen 5.0
  *
@@ -367,7 +367,7 @@ int ime_set_window_creation_defer_flag(bool flag);
  *
  * @remarks The ime_optimization_hint_set_cb() callback function is called when an optimization hint is set
  *
- * @param[in] callback_func @c ime_optimization_hint_set_cb event callback function
+ * @param[in] callback_func @c ime_optimization_hint_set_cb() event callback function
  * @param[in] user_data User data to be passed to the callback function
  *
  * @return 0 on success, otherwise a negative error value
diff --git a/include/inputmethod_keydef.h b/include/inputmethod_keydef.h
index 5cb3102..9d266a9 100644
--- a/include/inputmethod_keydef.h
+++ b/include/inputmethod_keydef.h
@@ -275,7 +275,7 @@ typedef enum {
 /**
  * @brief Enumeration for the key masks.
  *        The key masks indicate which modifier keys is pressed down during the keyboard hit.
- *        The special IME_KEY_MASK_RELEASED indicates the key release event.
+ *        The special #IME_KEY_MASK_RELEASED indicates the key release event.
  * @since_tizen @if MOBILE 2.4 @else 3.0 @endif
  */
 typedef enum {
diff --git a/include/privilege_checker_private.h b/include/privilege_checker_private.h
index 5fbbe65..345affe 100644
--- a/include/privilege_checker_private.h
+++ b/include/privilege_checker_private.h
@@ -1,10 +1,10 @@
-#ifndef __PRIVILEGE_CHECKER_H
-#define __PRIVILEGE_CHECKER_H
+#ifndef __PRIVILEGE_CHECKER_H__
+#define __PRIVILEGE_CHECKER_H__
 
 #define IME_PRIVILEGE "http://tizen.org/privilege/ime"
 
-bool inputmethod_cynara_initialize();
-void inputmethod_cynara_finish();
+bool inputmethod_cynara_initialize(void);
+void inputmethod_cynara_finish(void);
 bool check_privilege(const char *uid, const char *privilege);
 
-#endif /*__PRIVILEGE_CHECKER_H */
+#endif /*__PRIVILEGE_CHECKER_H__ */
diff --git a/src/inputmethod.cpp b/src/inputmethod.cpp
index e5fb446..bf98918 100644
--- a/src/inputmethod.cpp
+++ b/src/inputmethod.cpp
@@ -1385,7 +1385,7 @@ EXPORT_API int ime_set_imengine(const char *engine_id)
     return IME_ERROR_NONE;
 }
 
-EXPORT_API int ime_flush_imengine()
+EXPORT_API int ime_flush_imengine(void)
 {
     ime_error_e retVal = IME_ERROR_NONE;
 
@@ -1402,7 +1402,7 @@ EXPORT_API int ime_flush_imengine()
     return IME_ERROR_NONE;
 }
 
-EXPORT_API int ime_reset_imengine()
+EXPORT_API int ime_reset_imengine(void)
 {
     ime_error_e retVal = IME_ERROR_NONE;
 
@@ -1455,7 +1455,7 @@ EXPORT_API int ime_request_hide(void)
 }
 
 //LCOV_EXCL_START
-EXPORT_API int ime_initialize()
+EXPORT_API int ime_initialize(void)
 {
     ime_error_e retVal = IME_ERROR_NONE;
 
@@ -1468,7 +1468,7 @@ EXPORT_API int ime_initialize()
     return retVal;
 }
 
-EXPORT_API int ime_prepare()
+EXPORT_API int ime_prepare(void)
 {
     ime_error_e retVal = IME_ERROR_NONE;
 
@@ -1487,7 +1487,7 @@ EXPORT_API int ime_prepare()
     return retVal;
 }
 
-EXPORT_API int ime_finalize()
+EXPORT_API int ime_finalize(void)
 {
     ime_error_e retVal = IME_ERROR_NONE;
 
diff --git a/src/privilege_checker.cpp b/src/privilege_checker.cpp
index 1e4c0aa..ba71cfc 100644
--- a/src/privilege_checker.cpp
+++ b/src/privilege_checker.cpp
@@ -23,7 +23,7 @@ cynara *p_cynara = NULL;
 }
 
 bool
-inputmethod_cynara_initialize()
+inputmethod_cynara_initialize(void)
 {
     int ret = cynara_initialize(&p_cynara, NULL);
     if (ret != CYNARA_API_SUCCESS)
@@ -33,7 +33,7 @@ inputmethod_cynara_initialize()
 }
 
 void
-inputmethod_cynara_finish()
+inputmethod_cynara_finish(void)
 {
     if (p_cynara)
         cynara_finish(p_cynara);