Update doxygen and error code

Change-Id: I1165008ea951eb5929f3ba727bbe9d13d9957b78

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 90f8c1b..fa1ec0e 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -66,5 +66,4 @@ SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${PROJECT_NAME}
 INSTALL(TARGETS ${PROJECT_NAME} DESTINATION ${LIB_INSTALL_DIR})
 INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc DESTINATION ${LIB_INSTALL_DIR}/pkgconfig)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/include/livebox.h DESTINATION include/${PROJECT_NAME})
-INSTALL(FILES ${CMAKE_SOURCE_DIR}/include/livebox-viewer_PG.h DESTINATION /usr/share/doc/${PROJECT_NAME})
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION /usr/share/license RENAME "lib${PROJECT_NAME}")

diff --git a/doc/image/PD.png b/doc/image/PD.png
new file mode 100644 (file)
index 0000000..ebb7367
Binary files /dev/null and b/doc/image/PD.png differ

diff --git a/doc/image/download_folder.png b/doc/image/download_folder.png
new file mode 100644 (file)
index 0000000..1e5e01b
Binary files /dev/null and b/doc/image/download_folder.png differ

diff --git a/doc/image/front.jpg b/doc/image/front.jpg
new file mode 100644 (file)
index 0000000..9d46441
Binary files /dev/null and b/doc/image/front.jpg differ

diff --git a/doc/image/image_format.png b/doc/image/image_format.png
new file mode 100644 (file)
index 0000000..8f79a0c
Binary files /dev/null and b/doc/image/image_format.png differ

diff --git a/doc/image/message.png b/doc/image/message.png
new file mode 100644 (file)
index 0000000..4cb7760
Binary files /dev/null and b/doc/image/message.png differ

diff --git a/doc/image/preload_folder.png b/doc/image/preload_folder.png
new file mode 100644 (file)
index 0000000..3dbbf64
Binary files /dev/null and b/doc/image/preload_folder.png differ

diff --git a/doc/image/script_format.png b/doc/image/script_format.png
new file mode 100644 (file)
index 0000000..1fec88a
Binary files /dev/null and b/doc/image/script_format.png differ

diff --git a/doc/image/stock.png b/doc/image/stock.png
new file mode 100644 (file)
index 0000000..fd274fe
Binary files /dev/null and b/doc/image/stock.png differ

diff --git a/doc/image/text_format.png b/doc/image/text_format.png
new file mode 100644 (file)
index 0000000..b492883
Binary files /dev/null and b/doc/image/text_format.png differ

diff --git a/doc/image/twitter.png b/doc/image/twitter.png
new file mode 100644 (file)
index 0000000..36bce25
Binary files /dev/null and b/doc/image/twitter.png differ

diff --git a/doc/image/weather.png b/doc/image/weather.png
new file mode 100644 (file)
index 0000000..2f41af1
Binary files /dev/null and b/doc/image/weather.png differ

diff --git a/doc/livebox-viewer_doc.h b/doc/livebox-viewer_doc.h
new file mode 100644 (file)
index 0000000..948705e
--- /dev/null
+++ b/doc/livebox-viewer_doc.h
@@ -0,0 +1,125 @@
+/*
+ * Copyright 2013  Samsung Electronics Co., Ltd
+ *
+ * Licensed under the Flora License, Version 1.1 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://floralicense.org/license/
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * \ingroup CAPI_LIVEBOX_FRAMEWORK Tizen livebox framework
+ * \defgroup CAPI_LIVEBOX_VIEWER_MODULE Application Programming Interfaces for the viewer application
+ * \brief API for livebox viewer (widget screen, home screen, ...)
+ * \section CAPI_LIVEBOX_VIEWER_MODULE_HEADER Required Header
+ * \#include <livebox.h>
+ * \section CAPI_LIVEBOX_VIEWER_MODULE_OVERVIEW Overview
+ * Tizen(SLP) homescreen S/W framework is supporing the live box. (aka widget which is similiar with the android widget)
+ *
+ * \image html front.jpg
+ *
+ * \subsection WhatIsTheLivebox 1. What is the Livebox
+ * The live box is the widget of the TIZEN.
+ *
+ * It works as a small application displayed on other applications' (such as homescreen, lockscreen, etc ...) view.
+ * Each live box can have (not a mandatory option) a PD (progressive disclosure) in which more detailed information can be found.
+ * The content of PD can be exposed when a certain gesture (e.g., flick-down) has been applied to the live box.
+ * If you are interested in developing a livebox, there are things you should know prior to making any source code for the box.
+ * To make your live box added to any live box viewer application (e.g., live panel in our case), then you need to create and prepare    
+ * controller(SO file), layout script (EDJE for a PD if necessary), configuration files.
+ *
+ * A livebox is managed by data provider, since each SO file of a livebox is loaded on and controlled by data provider using predefined ABI.
+ * A viewer will receive any livebox's content in forms of "image file", "buffer" or "text" and display the content in various formats on its window.
+ * A livebox developer needs to make sure that your live box generates desirable content in-time on a explicit update-request or periodic update.
+ *
+ * After a data provider loads a livebox's SO file, it then assigns a specific "file name" for the livebox via an argument of a livebox function.
+ * Since then the livebox just generates content using then given file name.
+ * Passing an image file (whose name is the previously given name) is the basic method for providing contents to the viewer.
+ * But if you want play animation or handles user event in real-time, you can use the buffer type.
+ *
+ * And you should prepare the content of the Progressive Disclosure.
+ * The Progressive Dislcosure is only updated by the "buffer" type. so you should prepare the layout script for it.
+ * If you didn't install any script file for progressive disclosure, the viewer will ignore the "flick down" event from your livebox.
+ *
+ * \subsubsection Livebox 1.1 Livebox
+ * Live box is a default content of your widget. It always displays on the screen and updated periodically.
+ * It looks like below captured images.
+ * \image html weather.png Weather Livebox
+ * \image html stock.png Stock Livebox
+ * \image html twitter.png Twitter Livebox
+ *
+ * \subsubsection ProgressiveDisclosure 1.2 Progressive Disclosure
+ * \image html PD.png Progressive Disclosure
+ * Progressive disclosure will be displayed when a user flicks down a livebox. (basically it depends on the implementation of the view applications)
+ * To supports this, a developer should prepare the layout script (EDJE only for the moment) of the livebox's PD. (or you can use the buffer directly)
+ * Data provider supports EDJE script but the developer can use various scripts if (which is BIG IF) their interpreters can be implemented based on evas & ecore.
+ *
+ * When a layout script has been installed, data provider can load and rendering the given layout on the buffer.
+ * The content on the buffer can be shared between applications that need to display the content on their window.
+ * Description data file is necessary to place proper content components in rendered layout.
+ * Check this page Description Data. 
+ *
+ * \subsubsection ClusterCategory 1.3 What is the "cluster" and "category"
+ * The cluster and the sub-cluster is just like the grouping concept.
+ * It is used for creating/destorying your livebox instance when the data provider receives any context event from the context engine.
+ * You will only get "user,created" cluster and "default" category(sub cluster) info.
+ *
+ * \subsection LiveboxContent 2. How the livebox can draw contents for viewer?
+ * There are several ways to update the content of a livebox.
+ *
+ * \li Image file based content updating
+ * \li Description file based content updating (with the layout script file)
+ * \li Buffer based content updating
+ *
+ * Each method has specific benefit for implementing the livebox.
+ *
+ * \subsubsection ImageFormat 2.1 Via image file
+ * This is the basic method for providing content of a livebox to the viewer application.
+ * But this can be used only for the livebox. (Unavailable for the progressive disclosure).
+ * When your livebox is created, the provider will assign an unique ID for your livebox(it would be a filename).
+ * You should keep that ID until your livebox is running. The ID will be passed to you via livebox_create function.
+ * \image html image_format.png
+ *
+ * When you need to update the output of your livebox, you should generate the image file using given ID(filename).
+ * Then the data provider will recognize the event of updated output of a livebox and it will send that event to the viewer to reload it on the screen.
+ *
+ * \subsubsection ScriptFormat 2.2 Via layout script
+ * \image html script_format.png
+ * This method is supported for static layout & various contents (text & image)
+ * When you develop your livebox, first design the layout of box content using script (edje is default)
+ * Then the provider will load it to the content buffer and start rendering.
+ * After the sciprt is loaded, you can fill it using description data format.
+ * liblivebox defines description data handling functions.
+ *
+ * \subsubsection TextFormat 2.3 Via text data
+ * \image html text_format.png
+ * This is the simplified method to update the content of livebox.
+ * So your box only need to update the text data using description data format.
+ * Then the viewer will parse it to fill its screen.
+ * So there is no buffer area, just viewer decide how handles it.
+ *
+ * \subsubsection BufferFormat 2.4 Via buffer
+ * This method is very complex to implement.
+ * The provider will give a content buffer to you, then your box should render its contents on this buffer.
+ * This type is only supported for 3rd party livebox such as OSP and WEB.
+ * Inhouse(EFL) livebox is not able to use this buffer type for the box content.
+ *
+ * \subsection PackageNTools 3. How can I get the development packages or tools?
+ *
+ * \subsection DevelopLivebox 4. How can I write a new livebox
+ *
+ * \subsection TestLivebox 5. How can I test my livebox
+ *
+ * \subsection LiveboxDirectory 6. Livebox directory hierachy
+ * \image html preload_folder.png
+ * \image html download_folder.png
+ *
+ */
+

diff --git a/include/livebox-viewer_PG.h b/include/livebox-viewer_PG.h
deleted file mode 100644 (file)
index 67a71d8..0000000
--- a/include/livebox-viewer_PG.h
+++ /dev/null
@@ -1,16 +0,0 @@
-/*
- * Copyright 2013  Samsung Electronics Co., Ltd
- *
- * Licensed under the Flora License, Version 1.1 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://floralicense.org/license/
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-

diff --git a/include/livebox.h b/include/livebox.h
index 32306df..da6414d 100644 (file)
--- a/include/livebox.h
+++ b/include/livebox.h
@@ -21,19 +21,28 @@
 extern "C" {
 #endif
 
+/*!
+ * \addtogroup CAPI_LIVEBOX_VIEWER_MODULE
+ * \{
+ */
+
+/*!
+ * \brief
+ * Structure for a Livebox instance
+ */
 struct livebox;
 
 /*!
- * \note size list
- * 172x172
- * 348x172
- * 348x348
- * 700x348
- * 700x172
- * 700x700
+ * \brief
+ * Use the default update period which is defined in the livebox package manifest.
  */
 #define DEFAULT_PERIOD -1.0f
 
+/*!
+ * \brief
+ * Mouse & Key event for buffer type Livebox or PD
+ * Viewer should send these events to livebox.
+ */
 enum content_event_type {
        CONTENT_EVENT_MOUSE_DOWN        = 0x00000001, /*!< LB mouse down event for livebox */
        CONTENT_EVENT_MOUSE_UP          = 0x00000002, /*!< LB mouse up event for livebox */
@@ -51,31 +60,36 @@ enum content_event_type {
        CONTENT_EVENT_PD_MASK           = 0x10000000,
        CONTENT_EVENT_LB_MASK           = 0x40000000,
 
-       LB_MOUSE_DOWN                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN,
-       LB_MOUSE_UP                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP,
-       LB_MOUSE_MOVE                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE,
-       LB_MOUSE_ENTER                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER,
-       LB_MOUSE_LEAVE                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE,
+       LB_MOUSE_DOWN                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the livebox */
+       LB_MOUSE_UP                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the livebox */
+       LB_MOUSE_MOVE                   = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Move move on the livebox */
+       LB_MOUSE_ENTER                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the livebox */
+       LB_MOUSE_LEAVE                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the livebox */
        LB_MOUSE_SET                    = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET,
        LB_MOUSE_UNSET                  = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET,
 
-       PD_MOUSE_DOWN                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN,
-       PD_MOUSE_UP                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP,
-       PD_MOUSE_MOVE                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE,
-       PD_MOUSE_ENTER                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER,
-       PD_MOUSE_LEAVE                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE,
+       PD_MOUSE_DOWN                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_DOWN, /*!< Mouse down on the PD */
+       PD_MOUSE_UP                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UP, /*!< Mouse up on the PD */
+       PD_MOUSE_MOVE                   = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_MOVE, /*!< Mouse move on the PD */
+       PD_MOUSE_ENTER                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_ENTER, /*!< Mouse enter to the PD */
+       PD_MOUSE_LEAVE                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_LEAVE, /*!< Mouse leave from the PD */
        PD_MOUSE_SET                    = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_SET,
        PD_MOUSE_UNSET                  = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_MOUSE_MASK | CONTENT_EVENT_MOUSE_UNSET,
 
-       LB_KEY_DOWN                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN,
-       LB_KEY_UP                       = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP,
+       LB_KEY_DOWN                     = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
+       LB_KEY_UP                       = CONTENT_EVENT_LB_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
 
-       PD_KEY_DOWN                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN,
-       PD_KEY_UP                       = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP,
+       PD_KEY_DOWN                     = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_DOWN, /*!< Key down on the livebox */
+       PD_KEY_UP                       = CONTENT_EVENT_PD_MASK | CONTENT_EVENT_KEY_MASK | CONTENT_EVENT_KEY_UP, /*!< Key up on the livebox */
 
-       CONTENT_EVENT_MAX       = 0xFFFFFFFF
+       CONTENT_EVENT_MAX               = 0xFFFFFFFF
 };
 
+/*!
+ * \brief
+ * Accessibility event for buffer type Livebox or PD.
+ * These event set are sync'd with Tizen accessibility event set.
+ */
 enum access_event_type {
        ACCESS_EVENT_PD_MASK            = 0x10000000,
        ACCESS_EVENT_LB_MASK            = 0x20000000,
@@ -91,16 +105,16 @@ enum access_event_type {
        ACCESS_EVENT_SCROLL_MOVE        = 0x00200000, /*!< LB accessibility scroll move */
        ACCESS_EVENT_SCROLL_UP          = 0x00400000, /*!< LB accessibility scroll up */
 
-       LB_ACCESS_HIGHLIGHT             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT,
-       LB_ACCESS_HIGHLIGHT_NEXT        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,
-       LB_ACCESS_HIGHLIGHT_PREV        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV,
-       LB_ACCESS_UNHIGHLIGHT           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT,
-       LB_ACCESS_ACTIVATE              = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE,
-       LB_ACCESS_ACTION_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN,
-       LB_ACCESS_ACTION_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP,
-       LB_ACCESS_SCROLL_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN,
-       LB_ACCESS_SCROLL_MOVE           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE,
-       LB_ACCESS_SCROLL_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP,
+       LB_ACCESS_HIGHLIGHT             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT,        /*!< Access event - Highlight an object in the livebox */
+       LB_ACCESS_HIGHLIGHT_NEXT        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,   /*!< Access event - Move highlight to the next object in a livebox */
+       LB_ACCESS_HIGHLIGHT_PREV        = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_HIGHLIGHT_PREV,   /*!< Access event - Move highlight to the prev object in a livebox */
+       LB_ACCESS_UNHIGHLIGHT           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_UNHIGHLIGHT,      /*!< Access event - Delete highlight from the livebox */
+       LB_ACCESS_ACTIVATE              = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTIVATE,         /*!< Access event - Launch or activate the highlighted object */
+       LB_ACCESS_ACTION_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_DOWN,      /*!< Access event - down */
+       LB_ACCESS_ACTION_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_ACTION_UP,        /*!< Access event - up */
+       LB_ACCESS_SCROLL_DOWN           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_DOWN,      /*!< Access event - scroll down */
+       LB_ACCESS_SCROLL_MOVE           = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_MOVE,      /*!< Access event - scroll move */
+       LB_ACCESS_SCROLL_UP             = ACCESS_EVENT_LB_MASK | ACCESS_EVENT_SCROLL_UP,        /*!< Access event - scroll up */
 
        PD_ACCESS_HIGHLIGHT             = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT,
        PD_ACCESS_HIGHLIGHT_NEXT        = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_HIGHLIGHT_NEXT,
@@ -114,7 +128,10 @@ enum access_event_type {
        PD_ACCESS_SCROLL_UP             = ACCESS_EVENT_PD_MASK | ACCESS_EVENT_SCROLL_UP
 };
 
-/* Exported to user app */
+/*!
+ * \brief
+ * Livebox LB content type
+ */
 enum livebox_lb_type {
        LB_TYPE_IMAGE = 0x01, /*!< Contents of a livebox is based on the image file */
        LB_TYPE_BUFFER = 0x02, /*!< Contents of a livebox is based on canvas buffer(shared) */
@@ -124,6 +141,10 @@ enum livebox_lb_type {
        LB_TYPE_INVALID = 0xFF
 };
 
+/*!
+ * \brief
+ * Livebox PD content type
+ */
 enum livebox_pd_type {
        PD_TYPE_BUFFER = 0x01, /*!< Contents of a PD is based on canvas buffer(shared) */
        PD_TYPE_TEXT = 0x02, /*!< Contents of a PD is based on formatted text file */
@@ -132,6 +153,11 @@ enum livebox_pd_type {
        PD_TYPE_INVALID = 0xFF
 };
 
+/*!
+ * \brief
+ * Livebox event type.
+ * These event will be sent from the provider.
+ */
 enum livebox_event_type { /*!< livebox_event_handler_set Event list */
        LB_EVENT_LB_UPDATED, /*!< Contents of the given livebox is updated */
        LB_EVENT_PD_UPDATED, /*!< Contents of the given pd is updated */
@@ -152,13 +178,13 @@ enum livebox_event_type { /*!< livebox_event_handler_set Event list */
        LB_EVENT_HOLD_SCROLL, /*!< If the screen should be freezed */
        LB_EVENT_RELEASE_SCROLL, /*!< If the screen can be scrolled */
 
-       LB_EVENT_LB_UPDATE_BEGIN,
-       LB_EVENT_LB_UPDATE_END,
+       LB_EVENT_LB_UPDATE_BEGIN, /*!< Livebox LB content update is started */
+       LB_EVENT_LB_UPDATE_END, /*!< Livebox LB content update is finished */
 
-       LB_EVENT_PD_UPDATE_BEGIN,
-       LB_EVENT_PD_UPDATE_END,
+       LB_EVENT_PD_UPDATE_BEGIN, /*!< Livebox PD content update is started */
+       LB_EVENT_PD_UPDATE_END, /*!< Livebox PD content update is finished */
 
-       LB_EVENT_UPDATE_MODE_CHANGED,
+       LB_EVENT_UPDATE_MODE_CHANGED, /*!< Livebox Update mode is changed */
 
        LB_EVENT_IGNORED /*!< Request is ignored */
 };
@@ -168,7 +194,11 @@ enum livebox_fault_type {
        LB_FAULT_PROVIDER_DISCONNECTED /*!< Provider is disconnected */
 };
 
-enum livebox_visible_state { /*!< Must be sync'd with the provider */
+/*!
+ * \brief
+ * Must be sync'd with the provider
+ */
+enum livebox_visible_state {
        LB_SHOW = 0x00, /*!< Livebox is showed. Default state */
        LB_HIDE = 0x01, /*!< Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again */
 
@@ -178,7 +208,7 @@ enum livebox_visible_state { /*!< Must be sync'd with the provider */
 };
 
 /*!
- * \note
+ * \brief
  * TEXT type livebox contents handling opertators.
  */
 struct livebox_script_operators {
@@ -199,338 +229,716 @@ struct livebox_script_operators {
 };
 
 /*!
- * \brief Prototype of the return callback of every async functions.
- * \param[in] handle
- * \param[in] ret
- * \param[in] data
+ * \brief Prototype of the return callback of every async functions
+ * \details N/A
+ * \remarks N/A
+ * \param[in] handle Handle of the livebox instance
+ * \param[in] ret Result status of operation. LB_STATUS_XXX defined from liblivebox-service
+ * \param[in] data data for result callback
  * \return void
+ * \pre N/A
+ * \post N/A
+ * \see livebox_add
+ * \see livebox_add_with_size
+ * \see livebox_del
+ * \see livebox_activate
+ * \see livebox_resize
+ * \see livebox_set_group
+ * \see livebox_set_period
+ * \see livebox_access_event
+ * \see livebox_set_pinup
+ * \see livebox_create_pd
+ * \see livebox_create_pd_with_position
+ * \see livebox_destroy_pd
+ * \see livebox_emit_text_signal
+ * \see livebox_acquire_pd_pixmap
+ * \see livebox_acquire_lb_pixmap
+ * \see livebox_set_update_mode
  */
 typedef void (*ret_cb_t)(struct livebox *handle, int ret, void *data);
 
 /*!
  * \brief Initialize the livebox system
+ * \details N/A
+ * \remarks N/A
  * \param[in] disp If you have X Display connection object, you can re-use it. but you should care its life cycle.
  *                 It must be alive before call the livebox_fini
- * \return int 0 if success or < 0 (errno)
- * \sa livebox_fini
+ * \return int
+ * \retval LB_STATUS_SUCCESS if success
+ * \pre N/A
+ * \post N/A
+ * \see livebox_fini
  */
 extern int livebox_init(void *disp);
 
 /*!
  * \brief Finalize the livebox system
- * \return int 0 if success, -EINVAL if livebox_init is not called.
- * \sa livebox_init
+ * \details N/A
+ * \remarks N/A
+ * \return int
+ * \retval LB_STATUS_SUCCES if success
+ * \retval LB_STATUS_ERROR_INVALID if livebox_init is not called.
+ * \pre N/A
+ * \post N/A
+ * \see livebox_init
  */
 extern int livebox_fini(void);
 
 /*!
  * \brief Client is paused.
- * \return int 0 if success, -EFAULT if it failed to send state(paused) info
- * \sa livebox_client_resumed
+ * \details N/A
+ * \remarks N/A
+ * \return int
+ * \retval LB_STATUS_SUCCESS if success
+ * \retval LB_STATUS_ERROR_FAULT if it failed to send state(paused) info
+ * \pre N/A
+ * \post N/A
+ * \see livebox_client_resumed
  */
 extern int livebox_client_paused(void);
 
 /*!
  * \brief Client is rfesumed.
- * \return int 0 if success, -EFAULT if it failed to send state(resumed) info
- * \sa livebox_client_paused
+ * \details N/A
+ * \remarks N/A
+ * \return int
+ * \retval LB_STATUS_SUCCESS if success
+ * \retval LB_STATUS_ERROR_FAULT if it failed to send state(resumed) info
+ * \pre N/A
+ * \post N/A
+ * \see livebox_client_paused
  */
 extern int livebox_client_resumed(void);
 
 /*!
  * \brief Add a new livebox
+ * \details N/A
+ * \remarks
+ *    Even though you get the livebox handle from return value of this function,
+ *    it is not matured before return callback called.
+ *    You have to use the handle after get the return callback with "ret == LB_STATUS_SUCCESS"
  * \param[in] pkgname Livebox Id
- * \param[in] content Will be passed to the livebox.
- * \param[in] cluster
- * \param[in] category
+ * \param[in] content Will be passed to the livebox instance.
+ * \param[in] cluster Main group
+ * \param[in] category Sub group
  * \param[in] period Update period. if you set DEFAULT_PERIOD, the provider will use the default period which is described in the manifest.
  * \param[in] cb After send the request to the provider, its result will be passed
  * \param[in] data
  * \return handle
+ * \retval NULL if it fails to add a new instance
+ * \retval handle livebox handle
+ * \pre N/A
+ * \post
+ * \see ret_cb_t
+ * \see livebox_add_with_size
  */
 extern struct livebox *livebox_add(const char *pkgname, const char *content, const char *cluster, const char *category, double period, ret_cb_t cb, void *data);
+
+/*!
+ * \brief Add a new livebox
+ * \details
+ * Normal mode livebox
+ * 1x1=175x175
+ * 2x1=354x175
+ * 2x2=354x354
+ * 4x1=712x175
+ * 4x2=712x354
+ * 4x4=712x712
+ *
+ * Extended sizes
+ * 4x3=712x533
+ * 4x5=712x891
+ * 4x6=712x1070
+ *
+ * Easy mode livebox
+ * 21x21=224x215
+ * 23x21=680x215
+ * 23x23=680x653
+ *
+ * Special livebox
+ * 0x0=720x1280
+ * \remarks
+ *    Even if you get the handle by return value of this function, it is not created instance.
+ *    So you have to deal it as not initialized handle.
+ *    Only it can be initialized after get the return callback with "ret == LB_STATUS_SUCCESS".
+ * \param[in] pkgname Livebox Id
+ * \param[in] content Will be passed to the livebox instance.
+ * \param[in] cluster Main group
+ * \param[in] category Sub group
+ * \param[in] period DEFAULT_PERIOD can be used for this. this argument will be used to specify the period of update content of livebox.
+ * \param[in] type Size type - which are defined from liblivebox-service package.
+ * \param[in] cb After the request is sent to the master provider, this callback will be called.
+ * \param[in] data This data will be passed to the callback.
+ * \return handle
+ * \retval handle Livebox handle but not yet initialized
+ * \retval NULL if it fails to create a handle
+ * \see ret_cb_t
+ * \see livebox_add
+ */
 extern struct livebox *livebox_add_with_size(const char *pkgname, const char *content, const char *cluster, const char *category, double period, int type, ret_cb_t cb, void *data);
 
 /*!
  * \brief Delete a livebox
- * \param[in] handle
- * \param[in] ret_cb_t return callback
+ * \details N/A
+ * \remarks
+ *    If you call this with uninitialized handle, the return callback will be called synchronously.
+ *    So before return from this function, the return callback will be called first.
+ * \param[in] handler Handle of a livebox instance
+ * \param[in] cb return callback
  * \param[in] data user data for return callback
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval LB_STATUS_ERROR_BUSY already in process
+ * \retval LB_STATUS_ERROR_FAULT failed to create a request packet
+ * \retval LB_STATUS_SUCCESS successfully sent, return callack will be called
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_del(struct livebox *handler, ret_cb_t cb, void *data);
 
 /*!
  * \brief Set a livebox events callback
+ * \details
+ *    To get the events push from the provider, register the event callback using this function
+ *    The callback will be called if there is any events from the provider.
+ * \remarks N/A
  * \param[in] cb Event handler
  * \param[in] data User data for the event handler
  * \return int
- * \sa livebox_unset_event_handler
+ * \retval LB_STATUS_SUCCESS if succeed to set event handler
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval LB_STATUS_ERROR_MEMORY Not enough memory
+ * \pre NULL
+ * \post NULL
+ * \see livebox_unset_event_handler
  */
-
 extern int livebox_set_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data), void *data);
 
 /*!
  * \brief Unset the livebox event handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] cb
- * \return void * pointer of 'data' which is registered from the livebox_event_handler_set
- * \sa livebox_set_event_handler
+ * \return void *
+ * \retval pointer of 'data' which is used with the livebox_set_event_handler
+ * \pre N/A
+ * \post N/A
+ * \see livebox_set_event_handler
  */
 extern void *livebox_unset_event_handler(int (*cb)(struct livebox *handler, enum livebox_event_type event, void *data));
 
 /*!
- * \note
+ * \brief Live box fault event handler registeration function
  *   argument list
  *     event, pkgname, filename, funcname
- *
- * \brief Live box fault event handler registeration function
+ * \details N/A
+ * \remarks N/A
  * \param[in] cb
  * \param[in] data
  * \return int
- * \sa livebox_unset_fault_handler
+ * \retval LB_STATUS_SUCCESS if succeed to set fault event handler
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval LB_STATUS_ERROR_MEMORY Not enough memory
+ * \pre N/A
+ * \post N/A
+ * \see livebox_unset_fault_handler
  */
 extern int livebox_set_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *), void *data);
 
 /*!
  * \brief Unset the live box fault event handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] cb
- * \return pointer of 'data'
- * \sa livebox_set_fault_handler
+ * \return void *
+ * \retval pointer of 'data' which is used with the livebox_set_fault_handler
+ * \pre N/A
+ * \post N/A
+ * \see livebox_set_fault_handler
  */
 extern void *livebox_unset_fault_handler(int (*cb)(enum livebox_fault_type, const char *, const char *, const char *, void *));
 
 /*!
  * \brief Activate the faulted livebox.
+ * \details
+ *    Request result will be back via return callback.
+ * \remarks
+ *    Even though this function returns SUCCESS, it means just successfully sent a request to provider.
+ *    So you have to check the return callback. and its "ret" argument.
  * \param[in] pkgname
  * \param[in] cb
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_SUCCESS Successfully sent a request
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval LB_STATUS_ERROR_FAULT Failed to make a request
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_activate(const char *pkgname, ret_cb_t cb, void *data);
 
 /*!
  * \brief Resize the livebox
+ * \details
+ * Normal mode livebox size
+ * 1x1=175x175
+ * 2x1=354x175
+ * 2x2=354x354
+ * 4x1=712x175
+ * 4x2=712x354
+ * 4x4=712x712
+ *
+ * Extended livebox size
+ * 4x3=712x533
+ * 4x5=712x891
+ * 4x6=712x1070
+ *
+ * Easy mode livebox size
+ * 21x21=224x215
+ * 23x21=680x215
+ * 23x23=680x653
+ *
+ * Special mode livebox size
+ * 0x0=720x1280
+ * \remarks
+ *    You have to check the return callback.
  * \param[in] handler Handler of a livebox
  * \param[in] type Type of a livebox size, LB_SIZE_TYPE_1x1, ...
  * \param[in] cb Result callback of the resize operation.
  * \param[in] data User data for return callback
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval LB_STATUS_ERROR_BUSY Previous request of resize is in progress.
+ * \retval LB_STATUS_ERROR_ALREADY Already resized, there is no differences between current size and requested size.
+ * \retval LB_STATUS_ERROR_PERMISSION Permission denied, you only have view the content of this box.
+ * \retval LB_STATUS_ERROR_FAULT Failed to make a request
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *data);
 
 /*!
  * \brief Send the click event for a livebox.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler Handler of a livebox
  * \param[in] x Rational X of the content width.
  * \param[in] y Rational Y of the content height.
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_click(struct livebox *handler, double x, double y);
 
 /*!
  * \brief Change the cluster/sub-cluster name of given livebox handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler Handler of a livebox
  * \param[in] cluster New cluster of a livebox
  * \param[in] category New category of a livebox
  * \param[in] cb Result callback for changing the cluster/category of a livebox
  * \param[in] data User data for the result callback
  * \return int
+ * \retval LB_STATUS_SUCCESS Request is successfully sent. the return callback will be called.
+ * \retval LB_STATUS_ERROR_BUSY previous request is not finished yet.
+ * \retval LB_STATUS_ERROR_ALREADY group name is same with current one.
+ * \retval LB_STATUS_ERROR_PERMISSION you have no permission to change property of this livebox instance.
+ * \retval LB_STATUS_ERROR_FAULT Failed to make a request.
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_set_group(struct livebox *handler, const char *cluster, const char *category, ret_cb_t cb, void *data);
 
 /*!
  * \brief Get the cluster and category(sub-cluster) name of given livebox (It is not I18N format, only english)
+ * \details N/A
+ * \remarks
+ *    You have to do not release the cluster & category.
+ *    It is allocated inside of given livebox instance, so you can only read it.
  * \param[in] handler Handler of a livebox
  * \param[out] cluster Storage(memory) for containing the cluster name
  * \param[out] category Storage(memory) for containing the category name
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_get_group(struct livebox *handler, char ** const cluster, char ** const category);
 
 /*!
  * \brief Get the period of this livebox handler
+ * \details N/A
+ * \remarks
+ *    if this function returns 0.0f, it means the livebox has no update period.
+ *    or the handle is not valid.
+ *    This function only can be works after the return callback of livebox_create fucntion is called.
  * \param[in] handler Handler of a livebox
- * \return double Current update period of a livebox
+ * \return double
+ * \retval Current update period of a livebox
+ * \retval 0.0f it means the box has no update period, or it can returns 0.0 if the handles is not valid.
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern double livebox_period(struct livebox *handler);
 
 /*!
  * \brief Change the update period
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler Handler of a livebox
  * \param[in] period New update period of a livebox
  * \param[in] cb Result callback of changing the update period of this livebox
  * \param[in] data User data for the result callback
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_ALREADY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_set_period(struct livebox *handler, double period, ret_cb_t cb, void *data);
 
 /*!
  * \brief Is this an text type livebox?
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return content_type
+ * \return livebox_lb_type
+ * \retval LB_TYPE_IMAGE Contents of a livebox is based on the image file
+ * \retval LB_TYPE_BUFFER Contents of a livebox is based on canvas buffer(shared)
+ * \retval LB_TYPE_TEXT Contents of a livebox is based on formatted text file
+ * \retval LB_TYPE_PIXMAP Contens of a livebox is shared by the pixmap(depends on X)
+ * \retval LB_TYPE_INVALID
+ * \pre N/A
+ * \post N/A
+ * \see livebox_lb_type
  */
 extern enum livebox_lb_type livebox_lb_type(struct livebox *handler);
 
 /*!
  * \brief Is this livebox is created by a user?
+ * \details
+ *    If the livebox instance is created by system this will returns 0.
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID Invalid argument
+ * \retval 0 automatically created livebox by the provider
+ * \retval 1 created by user via livebox_add or livebox_add_with_size
+ * \pre N/A
+ * \post N/A
+ * \see livebox_add
+ * \see livebox_add_with_size
+ * \see livebox_set_event_handler
  */
 extern int livebox_is_user(struct livebox *handler);
 
 /*!
  * \brief Get the content information string of given livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return content
+ * \return char *
+ * \retval content_info Livebox content info that can be used again via content_info argument of livebox_add or livebox_add_with_size.
+ * \pre N/A
+ * \post N/A
+ * \see livebox_add
+ * \see livebox_add_with_size
  */
 extern const char *livebox_content(struct livebox *handler);
 
 /*!
  * \brief Get the sub cluster title string of given livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return sub cluster title
+ * \return const char *
+ * \retval sub cluster name
+ * \retval NULL
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern const char *livebox_category_title(struct livebox *handler);
 
 /*!
  * \brief Get the filename of given livebox, if it is an IMAGE type livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return filename
+ * \return const char *
+ * \retval filename if the livebox type is image this function will give you a abspath of an image file (content is rendered)
+ * \retval NULL if this has no image file or type is not image file.
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern const char *livebox_filename(struct livebox *handler);
 
 /*!
  * \brief Get the package name of given livebox handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return pkgname
+ * \return const char *
+ * \retval pkgname package name
+ * \retval NULL if the handler is not valid
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern const char *livebox_pkgname(struct livebox *handler);
 
 /*!
  * \brief Get the priority of a current content.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return priority
+ * \return double
+ * \retval 0.0f handler is NULL
+ * \retval -1.0f Handler is not valid (not yet initialized)
+ * \retval real number between 0.0 and 1.0
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern double livebox_priority(struct livebox *handler);
 
 /*!
  * \brief Acquire the buffer of given livebox (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return address of a FB
+ * \return void *
+ * \retval address of a FB
+ * \retval NULL if it fails to get fb address
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern void *livebox_acquire_fb(struct livebox *handler);
 
 /*!
  * \brief Release the buffer of a livebox (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] buffer
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_acquire_fb
  */
 extern int livebox_release_fb(void *buffer);
 
 /*!
  * \brief Get the reference count of Livebox buffer (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] buffer
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval refcnt positive integer including ZERO
+ * \pre N/A
+ * \post N/A
+ * \see livebox_pdfb_refcnt
  */
 extern int livebox_fb_refcnt(void *buffer);
 
 /*!
  * \brief Acquire the buffer of a PD frame (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval NULL
+ * \retval adress of buffer of PD
+ * \pre N/A
+ * \post N/A
+ * \see livebox_release_pdfb
  */
 extern void *livebox_acquire_pdfb(struct livebox *handler);
 
 /*!
  * \brief Release the acquired buffer of the PD Frame (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] buffer
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_acquire_pdfb
  */
 extern int livebox_release_pdfb(void *buffer);
 
 /*!
  * \brief Reference count of given PD buffer (Only for the buffer type)
+ * \details N/A
+ * \remarks N/A
  * \param[in] buffer
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval reference count
+ * \pre N/A
+ * \post N/A
+ * \see livebox_fb_refcnt
  */
 extern int livebox_pdfb_refcnt(void *buffer);
 
 /*!
  * \brief Get the size of the Livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \param[out] w
- * \param[out] h
  * \return int
+ * \retval LB_SIZE_TYPE_NxM
+ * \retval LB_SIZE_TYPE_INVALID
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_size(struct livebox *handler);
 
 /*!
  * \brief Get the size of the Progressive Disclosure
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[out] w
  * \param[out] h
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_get_pdsize(struct livebox *handler, int *w, int *h);
 
 /*!
  * \brief List of supported sizes of given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[out] cnt
- * \param[out] w
- * \param[out] h
+ * \param[out] size_list
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_get_supported_sizes(struct livebox *handler, int *cnt, int *size_list);
 
 /*!
  * \brief BUFFER SIZE of the livebox if it is a buffer type
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval size of livebox buffer
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_lbfb_bufsz(struct livebox *handler);
 
 /*!
  * \brief BUFFER SIZE of the progiressive disclosure if it is a buffer type
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval size of PD buffer
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_pdfb_bufsz(struct livebox *handler);
 
 /*!
  * \brief Send the content event (for buffer type) to provider(livebox)
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] type
  * \param[in] x
  * \param[in] y
- * \return
+ * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_access_event
  */
 extern int livebox_content_event(struct livebox *handler, enum content_event_type type, double x, double y);
 
 /*!
  * \brief Send the access event(for buffer type) to provider(livebox).
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \param[in] access_event_type
+ * \param[in] type
  * \param[in] x
  * \param[in] y
  * \param[in] cb
  * \param[in] data
- * \return
+ * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_content_event
  */
 extern int livebox_access_event(struct livebox *handler, enum access_event_type type, double x, double y, ret_cb_t cb, void *data);
 
 /*!
  * \brief Do pin up or not.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] flag
  * \param[in] cb
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval 1 box is pinned up
+ * \retval 0 box is not pinned up
+ * \see ret_cb_t
  */
 extern int livebox_set_pinup(struct livebox *handler, int flag, ret_cb_t cb, void *data);
 
 /*!
  * \brief Check the PIN-UP status of given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
  */
@@ -538,95 +946,178 @@ extern int livebox_is_pinned_up(struct livebox *handler);
 
 /*!
  * \brief Check the PINUP feature availability of the given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval 1 if the box support Pinup feature
+ * \retval 0 if the box does not support the Pinup feature
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_has_pinup(struct livebox *handler);
 
 /*!
  * \brief Check the PD existence of given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval 1 if the box support the PD
+ * \retval 0 if the box has no PD
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_has_pd(struct livebox *handler);
 
 /*!
  * \brief Create the PD of given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] cb
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_create_pd(struct livebox *handler, ret_cb_t cb, void *data);
 
 /*!
  * \brief Create the PD of given handler with the relative position from livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] x 0.0 ~ 1.0
  * \param[in] y 0.0 ~ 1.0
  * \param[in] cb
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_create_pd_with_position(struct livebox *handler, double x, double y, ret_cb_t cb, void *data);
 
 /*!
  * \brief PD position is updated.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] x 0.0 ~ 1.0
  * \param[in] y 0.0 ~ 1.0
- * \return int 0 if succeed to send request for updating position of the PD.
+ * \return int
+ * \retval LB_STATUS_SUCCESS if succeed to send request for updating position of the PD.
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_ERROR_INVALID
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_move_pd(struct livebox *handler, double x, double y);
 
 /*!
  * \brief Destroy the PD of given handler if it is created.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] cb
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see ret_cb_t
  */
 extern int livebox_destroy_pd(struct livebox *handler, ret_cb_t cb, void *data);
 
 /*!
  * \brief Check the create status of given livebox handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval 0 PD is not created
+ * \retval 1 PD is created
  */
 extern int livebox_pd_is_created(struct livebox *handler);
 
 /*!
  * \brief Check the content type of the progressive disclosure of given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
+ * \retval PD_TYPE_BUFFER Contents of a PD is based on canvas buffer(shared)
+ * \retval PD_TYPE_TEXT Contents of a PD is based on formatted text file
+ * \retval PD_TYPE_PIXMAP Contents of a livebox is shared by the pixmap(depends on X)
+ * \retval PD_TYPE_INVALID
+ * \pre N/A
+ * \post N/A
+ * \see livebox_pd_type
  */
 extern enum livebox_pd_type livebox_pd_type(struct livebox *handler);
 
 /*!
  * \brief Check the existence of a livebox about given package name
+ * \details N/A
+ * \remarks N/A
  * \param[in] pkgname
  * \return int
+ * \retval 1 if the box is exists
+ * \retval 0 if the box is not exists
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_is_exists(const char *pkgname);
 
 /*!
  * \brief Set function table for parsing the text content of a livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] ops
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \see livebox_set_pd_text_handler
  */
 extern int livebox_set_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
 
 /*!
  * \brief Set function table for parsing the text content of a Progressive Disclosure
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] ops
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \see livebox_set_text_handler
  */
 extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_script_operators *ops);
 
 /*!
  * \brief Emit a text signal to given livebox only if it is a text type.
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] emission
  * \param[in] source
@@ -636,132 +1127,244 @@ extern int livebox_set_pd_text_handler(struct livebox *handler, struct livebox_s
  * \param[in] ey
  * \param[in] cb
  * \param[in] data
+ * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \see ret_cb_t
  */
 extern int livebox_emit_text_signal(struct livebox *handler, const char *emission, const char *source, double sx, double sy, double ex, double ey, ret_cb_t cb, void *data);
 
 /*!
  * \brief Set a private data pointer to carry it using given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] data
  * \return int
+ * \retval LB_STATUS_SUCCESS
+ * \retval LB_STATUS_ERROR_INVALID
+ * \pre N/A
+ * \post N/A
+ * \see livebox_get_data
  */
 extern int livebox_set_data(struct livebox *handler, void *data);
 
 /*!
  * \brief Get private data pointer which is carried by given handler
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return int
+ * \return void *
+ * \retval data pointer
+ * \pre N/A
+ * \post N/A
+ * \see livebox_set_data
  */
 extern void *livebox_get_data(struct livebox *handler);
 
 /*!
  * \brief Subscribe the event for liveboxes only in given cluster and sub-cluster
+ * \details N/A
+ * \remarks N/A
  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
  *                      If you use the "*", value in the category will be ignored.
  * \param[in] category  "*" can be used for subscribe liveboxes events of all category(sub-cluster) in given "cluster"
- * \return int Success 0, fails error code
+ * \return int
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_unsubscribe_group
  */
 extern int livebox_subscribe_group(const char *cluster, const char *category);
 
 /*!
  * \brief Unsubscribe the event for the liveboxes, but you will receive already added liveboxes event.
+ * \details N/A
+ * \remarks N/A
  * \param[in] cluster   "*" can be used for subscribe all cluster's liveboxes event.
  *                      If you use the "*", value in the category will be ignored.
  * \param[in] category  "*" can be used for subscribe all sub-cluster's liveboxes event in given "cluster"
- * \return int Success 0, fails error code
+ * \return int
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_subscribe_group
  */
 extern int livebox_unsubscribe_group(const char *cluster, const char *category);
 
 /*!
  * \brief Refresh the group(cluster/sub-cluser(aka. category))
+ * \details N/A
+ * \remarks N/A
  * \param[in] cluster Cluster ID
  * \param[in] category Sub-cluster ID
- * \return int Success 0 or negative value
+ * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_refresh_group(const char *cluster, const char *category);
 
 /*!
  * \brief Refresh a livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
- * \return int Success 0 or negative value
+ * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_refresh(struct livebox *handler);
 
 /*!
  * \brief Pixmap Id of a livebox content
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
- * \sa livebox_pd_pixmap
+ * \retval 0 if the pixmap is not created
+ * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
+ * \pre N/A
+ * \post N/A
+ * \see livebox_pd_pixmap
  */
 extern int livebox_lb_pixmap(const struct livebox *handler);
 
 /*!
  * \brief Pixmap Id of a PD content
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \return int
- * \sa livebox_lb_pixmap
+ * \retval 0 if the pixmap is not created
+ * \retval pixmap Pixmap Id need to be casted to (unsigned int) type
+ * \pre N/A
+ * \post N/A
+ * \see livebox_lb_pixmap
  */
 extern int livebox_pd_pixmap(const struct livebox *handler);
 
 /*!
  * \brief
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] cb
  * \param[in] data
  * \return int
- * \sa livebox_release_pd_pixmap
- * \sa livebox_acquire_lb_pixmap
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_release_pd_pixmap
+ * \see livebox_acquire_lb_pixmap
+ * \see ret_cb_t
  */
 extern int livebox_acquire_pd_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
 
 /*!
  * \brief Release the acquired pixmap ID
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] pixmap
  * \return int
- * \sa livebox_acquire_pd_pixmap
- * \sa livebox_release_lb_pixmap
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_acquire_pd_pixmap
+ * \see livebox_release_lb_pixmap
  */
 extern int livebox_release_pd_pixmap(struct livebox *handler, int pixmap);
 
 /*!
  * \brief
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] cb
  * \param[in] data
  * \return int
- * \sa livebox_release_lb_pixmap
- * \sa livebox_acquire_pd_pixmap
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_release_lb_pixmap
+ * \see livebox_acquire_pd_pixmap
+ * \see ret_cb_t
  */
 extern int livebox_acquire_lb_pixmap(struct livebox *handler, ret_cb_t cb, void *data);
 
 /*!
  * \brief
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler
  * \param[in] pixmap
  * \return int
- * \sa livebox_acquire_lb_pixmap
- * \sa livebox_release_pd_pixmap
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see livebox_acquire_lb_pixmap
+ * \see livebox_release_pd_pixmap
  */
 extern int livebox_release_lb_pixmap(struct livebox *handler, int pixmap);
 
 /*!
  * \brief Update the visible state of a livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler Handler of a livebox
  * \param[in] state Configure the current visible state of a livebox
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_PERMISSION
+ * \retval LB_STATUS_ERROR_ALREADY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern int livebox_set_visibility(struct livebox *handler, enum livebox_visible_state state);
 
 /*!
  * \brief Current visible state of a livebox
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler Handler of a livebox
- * \return enum visible state
+ * \return livebox_visible_state
+ * \retval LB_SHOW Livebox is showed. Default state
+ * \retval LB_HIDE Livebox is hide, Update timer is not be freezed. but you cannot receive any updates events. you should refresh(reload) the content of a livebox when you make this show again
+ * \retval LB_HIDE_WITH_PAUSE Livebix is hide, it will paused the update timer, but if a livebox update its contents, update event will come to you
+ * \retval LB_VISIBLE_ERROR To enlarge the size of this enumeration type
+ * \pre N/A
+ * \post N/A
+ * \see N/A
  */
 extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
 
 /*!
  * \brief Set the update mode of current livebox
+ * \details N/A
+ * \remarks N/A
  *        if you set 1 for active update mode, you should get buffer without updated event from provider.
  *       But is passive mode, you have to update content of a box when you get updated event.
  *       Default is Passive mode.
@@ -770,19 +1373,34 @@ extern enum livebox_visible_state livebox_visibility(struct livebox *handler);
  * \param[in] cb Result callback function
  * \param[in] data Callback data
  * \return int
+ * \retval LB_STATUS_ERROR_INVALID
+ * \retval LB_STATUS_ERROR_BUSY
+ * \retval LB_STATUS_ERROR_PERMISSION
+ * \retval LB_STATUS_ERROR_ALREADY
+ * \retval LB_STATUS_ERROR_FAULT
+ * \retval LB_STATUS_SUCCESS
+ * \see ret_cb_t
  */
 extern int livebox_set_update_mode(struct livebox *handler, int active_update, ret_cb_t cb, void *data);
 
 /*!
  * \brief Is this box in the active update mode?
+ * \details N/A
+ * \remarks N/A
  * \param[in] handler HAndler of a livebox
- * \return int 0 if passive mode or 1 if active mode or error code
+ * \return int
+ * \retval 0 if passive mode
+ * \retval 1 if active mode or error code
+ * \see N/A
  */
 extern int livebox_is_active_update(struct livebox *handler);
 
+/*!
+ * \}
+ */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif
-/* End of a file */

diff --git a/live.viewer/include/debug.h b/live.viewer/include/debug.h
index 5021bfa..2efc6dc 100644 (file)
--- a/live.viewer/include/debug.h
+++ b/live.viewer/include/debug.h
@@ -14,18 +14,6 @@
  * limitations under the License.
  */
 
-#if !defined(SECURE_LOGD)
-#define SECURE_LOGD LOGD
-#endif
-
-#if !defined(SECURE_LOGE)
-#define SECURE_LOGE LOGE
-#endif
-
-#if !defined(SECURE_LOGW)
-#define SECURE_LOGW LOGW
-#endif
-
 #if !defined(FLOG)
 #define DbgPrint(format, arg...)       SECURE_LOGD("[\e[32m%s/%s\e[0m:%d] " format, util_basename(__FILE__), __func__, __LINE__, ##arg)
 #define ErrPrint(format, arg...)       SECURE_LOGE("[\e[32m%s/%s\e[0m:%d] " format, util_basename(__FILE__), __func__, __LINE__, ##arg)

diff --git a/packaging/liblivebox-viewer.spec b/packaging/liblivebox-viewer.spec
index 17f3f7a..f26a2dd 100644 (file)
--- a/packaging/liblivebox-viewer.spec
+++ b/packaging/liblivebox-viewer.spec
@@ -57,7 +57,6 @@ mkdir -p %{buildroot}/%{_datarootdir}/license
 %files devel
 %defattr(-,root,root,-)
 %{_includedir}/livebox-viewer/livebox.h
-%{_datarootdir}/doc/livebox-viewer/livebox-viewer_PG.h
 %{_libdir}/pkgconfig/*.pc
 
 # End of a file

diff --git a/src/fb.c b/src/fb.c
index 13f6658..1d9fc75 100644 (file)
--- a/src/fb.c
+++ b/src/fb.c
@@ -458,7 +458,7 @@ int fb_release_buffer(void *data)
 
        if (!data) {
                ErrPrint("buffer data == NIL\n");
-               return 0;
+               return LB_STATUS_ERROR_INVALID;
        }
 
        buffer = container_of(data, struct buffer, data);
@@ -507,7 +507,7 @@ int fb_release_buffer(void *data)
                break;
        }
 
-       return 0;
+       return LB_STATUS_SUCCESS;
 }
 
 int fb_refcnt(void *data)

diff --git a/src/livebox.c b/src/livebox.c
index 5834a3e..27d1290 100644 (file)
--- a/src/livebox.c
+++ b/src/livebox.c
@@ -1094,7 +1094,7 @@ EAPI int livebox_resize(struct livebox *handler, int type, ret_cb_t cb, void *da
 
        if (handler->lb.width == w && handler->lb.height == h) {
                DbgPrint("No changes\n");
-               return LB_STATUS_ERROR_ALREADY;;
+               return LB_STATUS_ERROR_ALREADY;
        }
 
        packet = packet_create("resize", "ssii", handler->pkgname, handler->id, w, h);
@@ -2425,7 +2425,7 @@ EAPI int livebox_emit_text_signal(struct livebox *handler, const char *emission,
                destroy_cb_info(cbinfo);
        }
 
-       return LB_STATUS_ERROR_FAULT;
+       return ret;
 }
 
 EAPI int livebox_subscribe_group(const char *cluster, const char *category)
@@ -2433,7 +2433,7 @@ EAPI int livebox_subscribe_group(const char *cluster, const char *category)
        struct packet *packet;
 
        /*!
-        * \TODO
+        * \todo
         * Validate the group info using DB
         * If the group info is not valid, do not send this request
         */
@@ -2452,7 +2452,7 @@ EAPI int livebox_unsubscribe_group(const char *cluster, const char *category)
        struct packet *packet;
 
        /*!
-        * \TODO
+        * \todo
         * Validate the group info using DB
         * If the group info is not valid, do not send this request
         * AND Check the subscribed or not too