fix API description

Change-Id: Ic83954f5ded30d25949b24e07afb708a9737c6d1

3 files changed, 81 insertions, 92 deletions

diff --git a/doc/appcore-widget_doc.h b/doc/appcore-widget_doc.h
index 1a83d63..99b698c 100755
--- a/doc/appcore-widget_doc.h
+++ b/doc/appcore-widget_doc.h
@@ -14,28 +14,26 @@
  * limitations under the License.
  */
 
+
 /**
- *
  * @ingroup CAPI_WIDGET_FRAMEWORK
  * @defgroup CAPI_WIDGET_APP_MODULE Widget Application
- * @brief Widget application API
- *
+ * @brief Widget application API.
  * @section CAPI_WIDGET_APP_MODULE_HEADER Required Header
- *   \#include <widget_app.h>
- *   \#include <widget_app_efl.h>
+ * \#include <widget_app.h>
+ * \#include <widget_app_efl.h>
+ *
  * @section CAPI_WIDGET_APP_MODULE_OVERVIEW Overview
  * The @ref CAPI_WIDGET_APP_MODULE API provides functions for handling Tizen widget application state changes or system events. Tizen widget application can be shown in the home screen.
- * This APIs support making multiple widget instances per an application.
- *
+ * This API supports making multiple widget instances per an application.
  * This API provides interfaces for the following categories:
- * - Starting or exiting the main event loop
- * - Registering callbacks for application state change events
- * - Registering callbacks for basic system events
- * - Registering callbacks for instance state change events
+ * - Starting or exiting the main event loop.
+ * - Registering callbacks for application state change events.
+ * - Registering callbacks for basic system events.
+ * - Registering callbacks for instance state change events.
  *
  * @subsection CAPI_WIDGET_APP_MODULE_STATE_CHANGE_EVENT Registering Callbacks for Application State Change Events
- * As for Tizen widget application states, it is very simple and somewhat similer to Tizen service application states.
- *
+ * As for Tizen widget application states, it is very simple and somewhat similar to Tizen service application states.
  * <p>
  * <table>
  * <tr>
@@ -46,7 +44,7 @@
  *   <td>widget_app_create_cb()</td>
  *   <td>Hook to take necessary actions before the main event loop starts.
  *   Your UI generation code should be placed here so that you do not miss any events from your application UI.
- *   Please make sure that you should make a class handle and return it. It will be used when the event for creating widget instance is received.
+ *   Please make sure that you make a class handle and return it. It will be used when the event for creating widget instance is received.
  *   You can initialize shared resources for widget instances in this callback function as well.
  * </td>
  * </tr>
@@ -54,24 +52,23 @@
  *  <td> widget_app_terminate_cb() </td>
  *  <td> Hook to take necessary actions when your application is terminating.
  *   Your application should release all resources, especially any
- *   allocations and shared resources must be freed here so other running applications can fully use these shared resources.
+ *   allocations and shared resources must be freed here so that other running applications can fully use these shared resources.
  *  </td>
  * </tr>
  * </table>
  * </p>
- *
  * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
+ *
  * @image html widget_app_lifecycle.png "Widget Application States"
  *
  * @subsection CAPI_WIDGET_APP_MODULE_SYSTEM_EVENT Registering Callbacks for System Events
- * Tizen widget applications can receive system events with widget_app_add_event_handler() api.
+ * Tizen widget applications can receive system events with widget_app_add_event_handler() API.
  * The type of system events that can be received are same as Tizen UI applications except for APP_EVENT_DEVICE_ORIENTATION_CHANGED.
  * See @ref CAPI_APPLICATION_MODULE.
  * The event for APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported in this module.
- *
+
  * @subsection CAPI_WIDGET_APP_INSTNACE_STATE_CHANGE_EVENT Registering callbacks for instance state change events
- * As for Tizen widget instance states, it is somewhat similer to Tizen application states.
- *
+ * As for Tizen widget instance states, it is somewhat similar to Tizen application states.
  * <p>
  * <table>
  * <tr>
@@ -82,7 +79,7 @@
  *   <td> widget_instance_create_cb() </td>
  *   <td> Called after widget instance is created.
  *    In this callback, you can initialize resources for this instance.
- *    If parameter 'content' is not NULL, You should restore the pervious status.
+ *    If parameter 'content' is not NULL, you should restore the pervious status.
  *   </td>
  * </tr>
  * <tr>
@@ -117,13 +114,11 @@
  * </tr>
  * </table>
  * </p>
- *
  * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
+ *
  * @image html widget_obj_lifecycle.png "Widget Instance States"
  *
  * @section CAPI_WIDGET_APP_MODULE_RELATED_FEATURES Related Features
  * This API is related with the following feature:
  * - http://tizen.org/feature/shell.appwidget
- *
- *
  */
diff --git a/include/widget_app.h b/include/widget_app.h
index 3cd38a0..da53d6b 100755
--- a/include/widget_app.h
+++ b/include/widget_app.h
@@ -33,6 +33,7 @@ extern "C" {
  * @{
  */
 
+
 /**
  * @brief Destroy type of widget instance.
  * @since_tizen 2.3.1
@@ -40,28 +41,29 @@ extern "C" {
 typedef enum widget_app_destroy_type {
 	WIDGET_APP_DESTROY_TYPE_PERMANENT = 0x00, /**< User deleted this widget from the viewer */
 	WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x01, /**< Widget is deleted because of other reasons (e.g. widget process is terminated temporarily by the system) */
-} widget_app_destroy_type_e;
+} widget_app_destroy_type_e; /**< Delete type */
+
 
 /**
- * @brief The handle for widget class.
+ * @brief The widget class handle.
  * @since_tizen 2.3.1
  */
 typedef struct _widget_class *widget_class_h;
 
+
 /**
- * @brief The handle for widget context.
+ * @brief The widget context handle.
  * @since_tizen 2.3.1
  */
 typedef struct _widget_context *widget_context_h;
 
+
 /**
  * @brief Called when the widget instance starts.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called after widget instance is created.
  *          In this callback, you can initialize resources for this instance.
- *
- * @param[in] context The context of widget instance.
+ * @param[in] context The context of widget instance
  * @param[in] content The data set for the previous status
  * @param[in] w The pixel value for widget width
  * @param[in] h The pixel value for widget height
@@ -72,37 +74,34 @@ typedef struct _widget_context *widget_context_h;
  */
 typedef int (*widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data);
 
+
 /**
  * @brief Called before the widget instance is destroyed.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called before widget instance is destroyed.
  *          In this callback, you can finalize resources for this instance.
- *          If reason is not #WIDGET_APP_DESTROY_TYPE_TEMPORARY, It should store the current status by using incoming bundle.
- *
- * @param[in] context The context of widget instance.
- * @param[in] reason The reason for destruction
- * @param[in,out] content The data set to save
- * @param[in] user_data The user data passed from widget_app_class_create function
+ *          If reason is not #WIDGET_APP_DESTROY_TYPE_TEMPORARY, it should store the current status by using incoming bundle.
  * @remark Note that the parameter 'content' is used to save the status of the widget instance.
  *         As a input parameter, content contains the saved status of the widget instance.
  *         You can fill the content parameter with the current status in this callback,
  *         then the framework will save the content by receiving it as a output parameter.
  *         Consequently, you should not use widget_app_context_set_content_info() api in this callback.
  *         The content will be overwritten after this callback returns with the 'content' parameter.
- *
+ * @param[in] context The context of widget instance
+ * @param[in] reason The reason for destruction
+ * @param[in,out] content The data set to save
+ * @param[in] user_data The user data passed from widget_app_class_create function
  * @return #WIDGET_ERROR_NONE on success,
  *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  */
 typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data);
 
+
 /**
  * @brief Called when the widget is invisible.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called when the widget is invisible.
  *          The paused instance may be destroyed by framework.
- *
  * @param[in] context The context of widget instance
  * @param[in] user_data The user data passed from widget_app_class_create function
  * @return #WIDGET_ERROR_NONE on success,
@@ -110,12 +109,11 @@ typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_d
  */
 typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_data);
 
+
 /**
  * @brief Called when the widget is visible.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called when the widget is visible.
- *
  * @param[in] context The context of widget instance
  * @param[in] user_data The user data passed from widget_app_class_create function
  * @return #WIDGET_ERROR_NONE on success,
@@ -123,12 +121,11 @@ typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_dat
  */
 typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_data);
 
+
 /**
  * @brief Called before the widget size is changed.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called before the widget size is changed.
- *
  * @param[in] context The context of widget instance
  * @param[in] w The pixel value for widget width
  * @param[in] h The pixel value for widget height
@@ -138,13 +135,12 @@ typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_da
  */
 typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data);
 
+
 /**
  * @brief Called when the event for updating widget is received.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called when the event for updating widget is received.
- *
- * @param[in] context The context of widget instance.
+ * @param[in] context The context of widget instance
  * @param[in] content The data set for updating this widget. It will be provided by requester.
  *                    Requester can use widget_service_trigger_update()
  * @param[in] force Although the widget is paused, if it is TRUE, the widget can be updated
@@ -155,6 +151,7 @@ typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h,
  */
 typedef int (*widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data);
 
+
 /**
  * @brief The structure for lifecycle of a widget instance.
  * @since_tizen 2.3.1
@@ -168,14 +165,13 @@ typedef struct {
 	widget_instance_update_cb update; /**< The callback function is called when the event for updating widget is received. */
 } widget_instance_lifecycle_callback_s;
 
+
 /**
  * @brief Called when the application starts.
  * @since_tizen 2.3.1
- *
  * @details The callback function is called before the main loop of the application starts.
  *          In this callback, you can initialize resources which can be shared among widget instances.
  *          This function should return the handle for widget class so that it will be used for making instances of widget.
- *
  * @param[in] user_data The user data passed from the callback registration function
  * @return The object of widget class
  * @see widget_app_main()
@@ -192,17 +188,18 @@ typedef struct {
  */
 typedef widget_class_h (*widget_app_create_cb)(void *user_data);
 
+
 /**
  * @brief Called when the application's main loop exits.
  * @details This callback function is called once after the main loop of the application exits.
  *          You should release the application's resources in this function.
  * @since_tizen 2.3.1
- *
  * @param[in] user_data The user data passed from the callback registration function
  * @see widget_app_main()
  */
 typedef void (*widget_app_terminate_cb)(void *user_data);
 
+
 /**
  * @brief The structure for lifecycle of a widget application.
  * @since_tizen 2.3.1
@@ -212,31 +209,29 @@ typedef struct {
 	widget_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
 } widget_app_lifecycle_callback_s;
 
+
 /**
  * @brief Called for each widget context.
  * @since_tizen 2.3.1
- *
  * @details This function will be called in the function of widget_app_foreach_context repeatedly.
- *
  * @param[in] context The context for widget instance
  * @param[in] data The data for caller
- * @return true to continue with the next iteration of the loop,
- *         otherwise false to break out of the loop.
+ * @return @c true to continue with the next iteration of the loop,
+ *         otherwise @c false to break out of the loop
  * @see widget_app_foreach_context()
  */
 typedef bool (*widget_context_cb)(widget_context_h context, void *data);
 
+
 /**
  * @brief Runs the main loop of the application until widget_app_exit() is called.
  * @since_tizen 2.3.1
- *
  * @param[in] argc The argument count
  * @param[in] argv The argument vector
  * @param[in] callback The set of callback functions to handle application events
  * @param[in] user_data The user data to be passed to the callback functions
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
@@ -245,13 +240,13 @@ typedef bool (*widget_context_cb)(widget_context_h context, void *data);
  */
 int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data);
 
+
 /**
  * @brief Exits the main loop of the application.
  * @details The main loop of the application stops and widget_app_terminate_cb() is invoked.
  * @since_tizen 2.3.1
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
@@ -260,14 +255,13 @@ int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *call
  */
 int widget_app_exit(void);
 
+
 /**
  * @brief Finishes context for the widget instance.
  * @since_tizen 2.3.1
- *
  * @param[in] context The context for widget instance
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
@@ -275,15 +269,14 @@ int widget_app_exit(void);
  */
 int widget_app_terminate_context(widget_context_h context);
 
+
 /**
  * @brief Retrieves all widget contexts in this application.
  * @since_tizen 2.3.1
- *
  * @param[in] callback The iteration callback function
  * @param[in] data The data for the callback function
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_CANCELED The iteration is canceled
@@ -293,17 +286,16 @@ int widget_app_terminate_context(widget_context_h context);
  */
 int widget_app_foreach_context(widget_context_cb callback, void *data);
 
+
 /**
  * @brief Adds the system event handler.
  * @since_tizen 2.3.1
- *
  * @param[out] event_handler The event handler
  * @param[in] event_type The system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported
  * @param[in] callback The callback function
  * @param[in] user_data The user data to be passed to the callback function
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
@@ -319,11 +311,9 @@ int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_t
 /**
  * @brief Removes registered event handler.
  * @since_tizen 2.3.1
- *
  * @param[in] event_handler The event handler
- *
- * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ * @return #WIDGET_ERROR_NONE on success
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
@@ -332,25 +322,25 @@ int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_t
  */
 int widget_app_remove_event_handler(app_event_handler_h event_handler);
 
+
 /**
  * @brief Gets a widget instance id.
  * @since_tizen 2.3.1
- *
- * @param[in] context The context for widget instance
- *
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- * @return Widget ID on success, otherwise NULL
+ * @remark You must not free returned Widget ID
+ * @param[in] context The context for widget instance
+ * @return Widget ID on success,
+ *         otherwise NULL
  * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @exception #WIDGET_ERROR_FAULT Unrecoverable error
- * @remark You must not free returned Widget ID
  * @see get_last_result()
  */
 const char *widget_app_get_id(widget_context_h context);
 
+
 /**
  * @brief Makes a class for widget instances.
  * @since_tizen 2.3.1
- *
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  * @param[in] callback The set of lifecycle callbacks
  * @param[in] user_data The user data to be passed to the callback functions
@@ -363,42 +353,42 @@ const char *widget_app_get_id(widget_context_h context);
  */
 widget_class_h widget_app_class_create(widget_instance_lifecycle_callback_s callback, void *user_data);
 
+
 /**
  * @brief Sets a tag in the context.
  * @since_tizen 2.3.1
- *
  * @param[in] context The context for widget instance
  * @param[in] tag The value to save
- *
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
  */
 int widget_app_context_set_tag(widget_context_h context, void *tag);
 
+
 /**
  * @brief Gets the tag in the context.
  * @since_tizen 2.3.1
- *
  * @param[in] context The context for widget instance
  * @param[out] tag The value to get
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
  */
 int widget_app_context_get_tag(widget_context_h context, void **tag);
 
+
 /**
  * @brief Sets the content info to the widget.
  * @since_tizen 2.3.1
  * @param[in] context The context for widget instance
  * @param[in] content_info The data set to save
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successfully sent
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
@@ -407,13 +397,14 @@ int widget_app_context_get_tag(widget_context_h context, void **tag);
  */
 int widget_app_context_set_content_info(widget_context_h context, bundle *content_info);
 
+
 /**
  * @brief Sends the title to the widget.
  * @since_tizen 2.3.1
  * @param[in] context The context for widget instance
  * @param[in] title When an accessibility mode is turned on, this string will be read
  * @return #WIDGET_ERROR_NONE on success,
- *          otherwise an error code (see WIDGET_ERROR_XXX) on failure
+ *         otherwise an error code (see WIDGET_ERROR_XXX) on failure
  * @retval #WIDGET_ERROR_NONE Successfully sent
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
@@ -422,6 +413,7 @@ int widget_app_context_set_content_info(widget_context_h context, bundle *conten
  */
 int widget_app_context_set_title(widget_context_h context, const char *title);
 
+
 /**
  * @brief Adds an additional widget class for multi-class of widget instantiation.
  * @since_tizen 3.0
@@ -449,4 +441,3 @@ widget_class_h widget_app_class_add(widget_class_h widget_class, const char *cla
 #endif
 
 #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */
-
diff --git a/include/widget_app_efl.h b/include/widget_app_efl.h
index fd1a0c0..092f195 100644
--- a/include/widget_app_efl.h
+++ b/include/widget_app_efl.h
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+
 #ifndef __TIZEN_APPFW_WIDGET_APP_EFL_H__
 #define __TIZEN_APPFW_WIDGET_APP_EFL_H__
 
@@ -24,30 +25,32 @@
 extern "C" {
 #endif
 
+
 /**
  * @addtogroup CAPI_WIDGET_APP_MODULE
  * @{
  */
 
 /**
- * @brief Gets a evas object for the widget
+ * @brief Gets an Evas object for the widget.
  * @since_tizen 2.3.1
- *
  * @param[in] context The context for widget instance
- * @param[out] win Evas object for window
- *
- * @return 0 on success, otherwise a negative error value
- * @retval #WIDGET_ERROR_NONE Successfull
+ * @param[out] win evas object for window
+ * @return 0 on success,
+ *			otherwise a negative error value
+ * @retval #WIDGET_ERROR_NONE Successful
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_FAULT Failed to make evas object
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  */
 int widget_app_get_elm_win(widget_context_h context, Evas_Object **win);
 
+
 /**
  * @}
  */
 
+
 #ifdef __cplusplus
 }
 #endif