From: mk5004.lee <mk5004.lee@samsung.com>
Date: Tue, 3 Mar 2020 07:19:09 +0000 (+0900)
Subject: Update description for ambient-viewer
X-Git-Tag: submit/tizen/20200305.032544~8
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=69f84bd0bad9c76596ee87f728fa624e6c3d14c6;p=platform%2Fcore%2Fappfw%2Fwidget-viewer.git

Update description for ambient-viewer

Change-Id: Ic6073ccb6971705b6d777775029cc26f14e33bf7
Signed-off-by: mk5004.lee <mk5004.lee@samsung.com>
---

diff --git a/ambient-viewer/include/ambient_viewer.h b/ambient-viewer/include/ambient_viewer.h
index 3ade1e72..447ae5f8 100644
--- a/ambient-viewer/include/ambient_viewer.h
+++ b/ambient-viewer/include/ambient_viewer.h
@@ -14,88 +14,225 @@
  * limitations under the License.
  */
 
-#ifndef __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__
-#define __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__
+#ifndef __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__
+#define __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__
 
 #include <stdbool.h>
 #include <bundle.h>
 
-#include "ambient_viewer_surface.h"
+#include <ambient_viewer_surface.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @file ambient-viewer.h
- * @brief
+ * @brief The ambient viewer handle.
+ * @remarks This handle only for internal applications.
  */
+typedef void *ambient_viewer_h;
 
 /**
- * @addtogroup
- * @{
+ * @brief Enumeration for ambient event type.
+ * @remarks This enum only for internal applications.
  */
-
-typedef void *ambient_viewer_h;
-
 typedef enum {
-	AMBIENT_VIEWER_EVENT_AOD_PREPARE,
-	AMBIENT_VIEWER_EVENT_AOD_READY,
-	AMBIENT_VIEWER_EVENT_WATCH_CHANGED,
+	AMBIENT_VIEWER_EVENT_AOD_PREPARE, /**<AOD prepare */
+	AMBIENT_VIEWER_EVENT_AOD_READY, /**<AOD ready */
+	AMBIENT_VIEWER_EVENT_WATCH_CHANGED, /**<Watch changed */
 } ambient_event_type_e;
 
+/**
+ * @brief Enumeration for ambient viewer direction.
+ * @remarks This enum only for internal applications.
+ */
 typedef enum {
-	AMBIENT_VIEWER_DIRECTION_VIEWER_AND_WATCH,
-	AMBIENT_VIEWER_DIRECTION_VIEWER_TOP_APP,
-	AMBIENT_VIEWER_DIRECTION_ALL,
+	AMBIENT_VIEWER_DIRECTION_VIEWER_AND_WATCH, /**<Viewer and Watch */
+	AMBIENT_VIEWER_DIRECTION_VIEWER_TOP_APP, /**<Viewer and Top application */
+	AMBIENT_VIEWER_DIRECTION_ALL, /**<All */
 } ambient_viewer_direction_e;
 
+/**
+ * @brief The callback function for lifecycle added.
+ * @remarks This function only for internal applications.
+ * @remarks The @a surface should not be released.
+            The @a surface can be used until ambient viewer handle is released.
+ * @param[in] surface The ambient viewer surface handle
+ * @param[in] user_data The user data
+ */
 typedef void (*ambient_viewer_lifecycle_added_cb)(
 			ambient_viewer_surface_h surface, void *user_data);
 
+/**
+ * @brief The callback function for lifecycle removed.
+ * @remarks This function only for internal applications.
+ * @remarks The @a surface should not be released.
+            The @a surface can be used until ambient viewer handle is released.
+ * @param[in] surface The ambient viewer surface handle
+ * @param[in] user_data The user data
+ */
 typedef void (*ambient_viewer_lifecycle_removed_cb)(
 			ambient_viewer_surface_h surface, void *user_data);
 
+/**
+ * @brief The callback function for lifecycle updated.
+ * @remarks This function only for internal applications.
+ * @remarks The @a surface should not be released.
+            The @a surface can be used until ambient viewer handle is released.
+ * @param[in] surface The ambient viewer surface handle
+ * @param[in] user_data The user data
+ */
 typedef void (*ambient_viewer_lifecycle_updated_cb)(
 			ambient_viewer_surface_h surface, void *user_data);
 
+/**
+ * @brief The structure for lifecycle callback.
+ * @remarks This struct only for internal applications.
+ */
 typedef struct _ambient_viewer_lifecycle{
-	ambient_viewer_lifecycle_added_cb added;
-	ambient_viewer_lifecycle_removed_cb removed;
-	ambient_viewer_lifecycle_updated_cb updated;
+	ambient_viewer_lifecycle_added_cb added; /**<Added callback */
+	ambient_viewer_lifecycle_removed_cb removed; /**<Removed callback */
+	ambient_viewer_lifecycle_updated_cb updated; /**<Updated callback */
 } ambient_viewer_lifecycle_s;
 
+/**
+ * @brief Creates the ambient viewer handle.
+ * @remarks This function only for internal applications.
+ * @remarks @a handle must be released using ambient_viewer_destroy().
+ * @param[in] win The Evas Object
+ * @param[out] handle The ambient viewer handle
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AMBIENT_VIEWER_ERROR_OUT_OF_MEMORY Out of memory
+ * @see #ambient_viewer_h
+ * @see ambient_viewer_destroy()
+ */
 int ambient_viewer_create(Evas_Object *win, ambient_viewer_h *handle);
 
+/**
+ * @brief Releases the ambient viewer handle.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ */
 int ambient_viewer_destroy(ambient_viewer_h handle);
 
+/**
+ * @brief Notifies the ambient event.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @param[in] enter Whether to enter ambient mode
+ * @param[in] dir Direction to notify
+ * @param[in] extra The bundle handle
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @see #ambient_viewer_direction_e
+ */
 int ambient_viewer_notify_ambient_event(ambient_viewer_h handle, bool enter,
 			ambient_viewer_direction_e dir, bundle *extra);
 
+/**
+ * @brief Monitors the ambient event.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @param[in] lifecycle Whether to enter ambient mode
+ * @param[in] user_data The user data
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AMBIENT_VIEWER_ERROR_OUT_OF_MEMORY Out of memory
+ * @see #ambient_viewer_lifecycle_s
+ * @see ambient_viewer_unmonitor()
+ */
 int ambient_viewer_monitor(ambient_viewer_h handle,
 			ambient_viewer_lifecycle_s lifecycle, void *user_data);
 
+/**
+ * @brief Unmonitors the ambient event.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @see ambient_viewer_monitor()
+ */
 int ambient_viewer_unmonitor(ambient_viewer_h handle);
 
+/**
+ * @brief The callback function for ambient event.
+ * @remarks This function only for internal applications.
+ * @remarks The @a sender can be used only in the callback. To use outside, make a copy.
+            The @a extra is managed by the platform and will be released when ambient viewer handle destroy.
+ * @param[in] event The event type
+ * @param[in] sender The sender name
+ * @param[in] extra The bundle data
+ * @param[in] user_data The user data
+ */
 typedef void (*ambient_viewer_event_cb)(ambient_event_type_e event,
 			const char *sender, bundle *extra, void *user_data);
 
+/**
+ * @brief Sets the event listen callback.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @param[in] callback The callback func
+ * @param[in] user_data The user data
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AMBIENT_VIEWER_ERROR_OUT_OF_MEMORY Out of memory
+ * @see ambient_viewer_event_cb()
+ * @see ambient_viewer_unset_event_listener()
+ */
 int ambient_viewer_set_event_listener(ambient_viewer_h handle,
 			ambient_viewer_event_cb callback, void *user_data);
 
+/**
+ * @brief Unsets the event listen callback.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer handle
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @see ambient_viewer_set_event_listener()
+ */
 int ambient_viewer_unset_event_listener(ambient_viewer_h handle);
 
+/**
+ * @brief Gets the watch surface.
+ * @remarks This function only for internal applications.
+ * @remarks The @a surface should not be released.
+            The @a surface is available until handle is released.
+ * @param[in] handle The ambient viewer handle
+ * @param[out] surface The watch surface
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @see #ambient_viewer_surface_h
+ */
 int ambient_viewer_get_watch_surface(ambient_viewer_h handle,
 			ambient_viewer_surface_h *surface);
 
-int ambient_viewer_get_top_app_surface(ambient_viewer_h handle,
-			ambient_viewer_surface_h *surface);
-
 /**
- * @}
+ * @brief Gets the top app surface.
+ * @remarks This function only for internal applications.
+ * @remarks The @a surface should not be released.
+            The @a surface is available until handle is released.
+ * @param[in] handle The ambient viewer handle
+ * @param[out] surface The top app surface
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @see #ambient_viewer_surface_h
  */
+int ambient_viewer_get_top_app_surface(ambient_viewer_h handle,
+			ambient_viewer_surface_h *surface);
 
 #ifdef __cplusplus
 }
 #endif
-#endif /* __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__ */
\ No newline at end of file
+#endif /* __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_H__ */
diff --git a/ambient-viewer/include/ambient_viewer_common.h b/ambient-viewer/include/ambient_viewer_common.h
index 850a9504..3ca45ba6 100644
--- a/ambient-viewer/include/ambient_viewer_common.h
+++ b/ambient-viewer/include/ambient_viewer_common.h
@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__
-#define __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__
+#ifndef __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__
+#define __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__
 
 #include <tizen.h>
 
@@ -31,9 +31,8 @@ extern "C" {
 
 /**
  * @brief Enumeration for ambient_viewer error.
- * @since_tizen 5.5
+ * @remarks This enum only for internal applications.
  */
-
 typedef enum _ambient_viewer_error {
 	AMBIENT_VIEWER_ERROR_NONE = TIZEN_ERROR_NONE, /**< Success */
 	AMBIENT_VIEWER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
@@ -46,4 +45,4 @@ typedef enum _ambient_viewer_error {
 #ifdef __cplusplus
 }
 #endif
-#endif /* __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__ */
+#endif /* __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_COMMON_H__ */
diff --git a/ambient-viewer/include/ambient_viewer_surface.h b/ambient-viewer/include/ambient_viewer_surface.h
index 140a7c7c..4267e09e 100644
--- a/ambient-viewer/include/ambient_viewer_surface.h
+++ b/ambient-viewer/include/ambient_viewer_surface.h
@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__
-#define __AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__
+#ifndef __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__
+#define __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__
 
 #include <Evas.h>
 
@@ -23,38 +23,78 @@
 extern "C" {
 #endif
 
-/**
- * @file ambient-viewer.h
- * @brief
- */
 
 /**
- * @addtogroup
- * @{
+ * @brief The surface handle.
+ * @remarks This handle only for internal applications.
  */
-
 typedef const void *ambient_viewer_surface_h;
 
+/**
+ * @brief Gets the current image.
+ * @remarks This function only for internal applications.
+ * @remarks The @a image should not be released.
+            The @a image is available until handle is released.
+ * @param[in] handle The ambient viewer surface handle
+ * @param[out] image The Evas object
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ */
 int ambient_viewer_surface_get_cur_image(ambient_viewer_surface_h handle,
 			Evas_Object **image);
 
+/**
+ * @brief Gets whether the surface is a watch or not.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer surface handle
+ * @param[out] is_watch Whether it is a watch or not
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ */
 int ambient_viewer_surface_is_watch(ambient_viewer_surface_h handle,
 			bool *is_watch);
 
+/**
+ * @brief Gets the App ID.
+ * @remarks This function only for internal applications.
+ * @remarks The @a app_id should be released using free().
+ * @param[in] handle The ambient viewer surface handle
+ * @param[out] app_id A appid
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ */
 int ambient_viewer_surface_get_app_id(ambient_viewer_surface_h handle,
 			char **app_id);
 
+/**
+ * @brief Gets the Inastance ID.
+ * @remarks This function only for internal applications.
+ * @remarks The @a inst_id should be released using free().
+ * @param[in] handle The ambient viewer surface handle
+ * @param[out] inst_id A instance id
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
+ */
 int ambient_viewer_surface_get_inst_id(ambient_viewer_surface_h handle,
 			char **inst_id);
 
-int ambient_viewer_surface_get_opr(ambient_viewer_surface_h handle,
-			float *opr);
-
 /**
- * @}
+ * @brief Gets the opr of the Evas Object.
+ * @remarks This function only for internal applications.
+ * @param[in] handle The ambient viewer surface handle
+ * @param[out] opr The OPR (On Pixel Ratio)
+ * @return #AMBIENT_VIEWER_ERROR_NONE On success, other value on failure
+ * @retval #AMBIENT_VIEWER_ERROR_NONE Success
+ * @retval #AMBIENT_VIEWER_ERROR_INVALID_PARAMETER Invalid parameter
  */
+int ambient_viewer_surface_get_opr(ambient_viewer_surface_h handle,
+			float *opr);
 
 #ifdef __cplusplus
 }
 #endif
-#endif /*__AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__ */
+#endif /* __TIZEN_WIDGET_VEWER_AMBIENT_VIEWER_INCLUDE_AMBIENT_VIEWER_SURFACE_H__ */