Update doxygen

[platform/core/base/bundle.git] / include / bundle.h

diff --git a/include/bundle.h b/include/bundle.h
old mode 100755 (executable)
new mode 100644 (file)
index 9ace22d..1cb307a
--- a/include/bundle.h
+++ b/include/bundle.h
@@ -118,10 +118,10 @@ typedef void (*bundle_iterator_t) (const char *key, const int type, const bundle
  * @brief Creates a bundle object.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
- * @return The bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @return The bundle object,
+ *         @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
  * @see bundle_free()
  *
  * @code
@@ -138,8 +138,8 @@ API bundle *bundle_create(void);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] b The bundle object to be freed
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a b must be a valid bundle object.
  * @see bundle_create()
  *
@@ -160,10 +160,10 @@ API int bundle_free(bundle *b);
  * @param[in] str_array The string type value; if @c NULL, an empty array is created; you can change an item with
  * @param[in] len The length of the array
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
  * @pre @a b must be a valid bundle object.
  * @see bundle_get_str_array()
  *
@@ -184,9 +184,9 @@ API int bundle_add_str_array(bundle *b, const char *key, const char **str_array,
  * @param[in] b The bundle object
  * @param[in] key The given key
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  * @pre @a b must be a valid bundle object.
  *
  * @code
@@ -209,11 +209,11 @@ API int bundle_del(bundle *b, const char *key);
  * @param[in] b The bundle object
  * @param[in] key The key
  * @param[out] len The array length
- * @return The pointer to the array of strings
- * @retval @c NULL - Key not found
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @return The pointer to the array of strings,
+ *         @c NULL - Key not found
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  * @pre @a b must be a valid bundle object.
  * @see bundle_add_str_array()
  *
@@ -263,9 +263,9 @@ API int bundle_get_count(bundle *b);
  * @param[in] b A bundle
  * @param[in] key A key in the bundle
  * @return The type of a key in @a b
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @exception BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  * @pre @a b must be a valid bundle object.
  * @see bundle_type_t
  */
@@ -276,11 +276,12 @@ API int bundle_get_type(bundle *b, const char *key);
  * @brief Duplicates a given bundle object.
  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
+ *          The returned value should be released using bundle_free().
  * @param[in] b_from The bundle object to be duplicated
- * @return The new bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @return The new bundle object,
+ *         @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a b must be a valid bundle object.
  *
  * @code
@@ -305,8 +306,8 @@ API bundle *bundle_dup(bundle *b_from);
  * @param[in] b The bundle object
  * @param[in] iter The iteration callback function
  * @param[in] user_data The data for the callback function
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a b must be a valid bundle object.
  * @see bundle_keyval_get_type()
  * @see bundle_keyval_type_is_array()
@@ -357,10 +358,10 @@ API void bundle_foreach(bundle *b, bundle_iterator_t iter, void *user_data);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  * @param[in] kv A bundle_keyval_t object
- * @return The type of @a kv
- * @retval @c -1 - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @return The type of @a kv,
+ *         @c -1 - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a kv must be a valid bundle_keyval_t object.
  * @see bundle_foreach()
  */
@@ -373,10 +374,10 @@ API int bundle_keyval_get_type(bundle_keyval_t *kv);
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
  * @param[in] kv A bundle_keyval_t object
  * @return The operation result
- * @retval @c 1 - @a kv is an array
- * @retval @c 0 - @a kv is not an array
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ *         @c 1 - @a kv is an array
+ *         @c 0 - @a kv is not an array
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a kv must be a valid bundle_keyval_t object.
  * @see bundle_foreach()
  */
@@ -391,8 +392,8 @@ API int bundle_keyval_type_is_array(bundle_keyval_t *kv);
  * @param[out] val The value
  * @param[out] size The size of @a val
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a kv must be a valid bundle_keyval_t object.
  * @post @a val and @a size are set.
  * @see bundle_foreach()
@@ -408,10 +409,10 @@ API int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *siz
  * @param[out] array_len The length of @a array_val
  * @param[out] array_element_size The array of size of each array element
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a kv must be a valid bundle_keyval_t object.
- * @post @a array_val, @a array_len, @a array_item_size are set.
+ * @post @a array_val, @a array_len, @a array_element_size are set.
  * @see bundle_foreach()
  */
 API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
@@ -425,8 +426,8 @@ API int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsi
  *               @a r MUST BE FREED by free(r)
  * @param[out] len The size of @a r (in bytes)
  * @return The size of the raw data
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
  * @pre @a b must be a valid bundle object.
  *
  * @code
@@ -447,13 +448,14 @@ API int bundle_encode(bundle *b, bundle_raw **r, int *len);
  * @brief Deserializes bundle_raw and gets the bundle object.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
+ *          The returned value should be released using bundle_free().
  * @param[in] r The bundle_raw data to be converted to bundle object
  * @param[in] len The size of @a r
- * @return The bundle object
- * @retval @c NULL - Failure
- * @exception BUNDLE_ERROR_NONE Success
- * @exception BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @pre @a b must be a valid bundle object.
+ * @return The bundle object,
+ *         @c NULL - Failure
+ * @exception #BUNDLE_ERROR_NONE Success
+ * @exception #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @pre @a r must be a valid bundle object.
  *
  * @code
  #include <bundle.h>
@@ -482,10 +484,10 @@ API bundle *bundle_decode(const bundle_raw *r, const int len);
  * @param[in] key The key
  * @param[in] str The string type value
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
  * @pre @a b must be a valid bundle object.
  * @see bundle_get_str()
  * @code
@@ -508,10 +510,10 @@ API int bundle_add_str(bundle *b, const char *key, const char *str);
  * @param[in] bytes The byte sequence
  * @param[in] size The byte sequence size in bytes
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
- * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_EXISTS Key already exists
+ * @retval #BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
  * @pre @a b must be a valid bundle object.
  * @see bundle_get_byte()
  *
@@ -537,9 +539,9 @@ API int bundle_add_byte(bundle *b, const char *key, const void *bytes, const siz
  * @param[in] key The key
  * @param[out] str The returned value
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  * @pre @a b must be a valid bundle object.
  * @see bundle_add_str()
  *
@@ -561,15 +563,15 @@ API int bundle_get_str(bundle *b, const char *key, char **str);
 /**
  * @brief Gets the byte sequence with the given key.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
- * @remarks You must not free @a byte.
+ * @remarks You must not free @a bytes.
  * @param[in] b The bundle object
  * @param[in] key The key
  * @param[out] bytes The byte sequence
  * @param[out] size The byte sequence size in bytes
  * @return The operation result
- * @retval BUNDLE_ERROR_NONE Success
- * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
+ * @retval #BUNDLE_ERROR_NONE Success
+ * @retval #BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
  * @pre @a b must be a valid bundle object.
  * @see bundle_add_byte()
  *
@@ -615,8 +617,8 @@ API int bundle_add_byte_array(bundle *b, const char *key, const unsigned int len
 
 /**
  * @brief Sets an element of an array of byte sequences.
- * @since_tizen 5.5
  * @details The array will contain its own copy of the added value.
+ * @since_tizen 5.5
  *
  * @param[in]   b                       The bundle object
  * @param[in]   key                     The key