From 5952fedca21771977a0f8ea5975818a79a4a9430 Mon Sep 17 00:00:00 2001
From: SukhyungKang <shine.kang@samsung.com>
Date: Tue, 14 May 2024 14:30:40 +0900
Subject: [PATCH] Modify api documentation

Change-Id: I54f1e9007f7629f19a50cad59aa870868c3eb557
Signed-off-by: SukhyungKang <shine.kang@samsung.com>
---
 include/widget_app.h     | 24 ++++++++++++++++++++++++
 include/widget_app_efl.h | 18 ++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/include/widget_app.h b/include/widget_app.h
index f387349..a44e45e 100644
--- a/include/widget_app.h
+++ b/include/widget_app.h
@@ -289,6 +289,7 @@ int widget_app_foreach_context(widget_context_cb callback, void *data);
 /**
  * @brief Adds the system event handler.
  * @since_tizen 2.3.1
+ * @remarks The @a event_handler should be released using widget_app_remove_event_handler().
  * @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
@@ -300,6 +301,27 @@ int widget_app_foreach_context(widget_context_cb callback, void *data);
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
+ * @par Example
+ * @code
+#include <widget_app.h>
+
+static void
+widget_app_event_cb(app_event_info_h event_info, void *user_data)
+{
+}
+...
+int main()
+{
+  int ret;
+  app_event_handler_h event_handler = NULL;
+
+  r = widget_app_add_event_handler(&event_handler, APP_EVENT_LOW_BATTERY, widget_app_event_cb, NULL);
+  ...
+  r = widget_app_remove_event_handler(event_handler);
+
+  return 0;
+}
+ * @endcode
  * @see app_event_type_e
  * @see app_event_cb()
  * @see widget_app_remove_event_handler()
@@ -381,6 +403,7 @@ int widget_app_context_set_tag(widget_context_h context, void *tag);
 /**
  * @brief Gets the tag in the context.
  * @since_tizen 2.3.1
+ * @remarks Releasing the @a tag value depends on the value that set by widget_app_context_set_tag() function.
  * @param[in] context The context for widget instance
  * @param[out] tag The value to get
  * @return #WIDGET_ERROR_NONE on success,
@@ -389,6 +412,7 @@ int widget_app_context_set_tag(widget_context_h context, void *tag);
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_FAULT Unrecoverable error
+ * @see widget_app_context_set_tag()
  */
 int widget_app_context_get_tag(widget_context_h context, void **tag);
 
diff --git a/include/widget_app_efl.h b/include/widget_app_efl.h
index 8817395..5deb827 100644
--- a/include/widget_app_efl.h
+++ b/include/widget_app_efl.h
@@ -34,6 +34,7 @@ extern "C" {
 /**
  * @brief Gets an Evas object for the widget.
  * @since_tizen 2.3.1
+ * @remarks The @a win should be released using evas_object_del().
  * @param[in] context The context for widget instance
  * @param[out] win evas object for window
  * @return 0 on success,
@@ -42,6 +43,23 @@ extern "C" {
  * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
  * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #WIDGET_ERROR_FAULT Failed to make evas object
+ * @par Example
+ * @code
+#include <widget_app_efl.h>
+
+int widget_create(widget_context_h context)
+{
+  Evas_Object *win = NULL;
+  int ret;
+
+  ret = widget_app_elm_win(context, &win);
+  ...
+  evas_object_del(win)
+
+  return 0;
+}
+ * @endcode
+ * @see evas_object_del()
  */
 int widget_app_get_elm_win(widget_context_h context, Evas_Object **win);
 
-- 
2.7.4