Modify API description

This patch adds descriptions related to memory management.

Change-Id: Id283997d1dba1d7177ae6d7c23328b5c3f8c51e8
Signed-off-by: Hwankyu Jhun <h.jhun@samsung.com>

diff --git a/include/bundle.h b/include/bundle.h
index ef0aacb..00a18c0 100644 (file)
--- a/include/bundle.h
+++ b/include/bundle.h
@@ -400,6 +400,8 @@ int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
 /**
  * @brief Gets the value array, length of the array, and size of each array item.
  * @since_tizen 2.3
+ * @remarks The @a array_val should not be released.
+ *          The @a array_element_size should not be released.
  * @param[in] kv A bundle_keyval_t object
  * @param[out] array_val The array pointer of values
  * @param[out] array_len The length of @a array_val
@@ -409,6 +411,36 @@ int bundle_keyval_get_basic_val(bundle_keyval_t *kv, void **val, size_t *size);
  * @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_element_size are set.
+ * @code
+ #include <stdio.h>
+ #include <bundle.h>
+ void
+ sample_cb(const char *key, const int type, const bundle_keyval_t *kv, void *user_data)
+ {
+     void **array_val = NULL;
+     unsigned int array_len = 0;
+     size_t *array_elem_size = NULL;
+     unsigned int i;
+
+     printf("Key: %s, Type: %d\n", key, type);
+     if (bundle_keyval_type_is_array(kv)) {
+         bundle_keyval_get_array_val(kv, &array_val, &array_len, &array_elem_size);
+         for (i = 0; i < array_len; ++i) {
+             printf("Value[%u]: %s\n", i, (const char *)array_val[i]);
+         }
+     }
+ }
+
+ int main(void)
+ {
+     bundle *b = bundle_create();
+     const char *s_arr[] = {"abc", "bcd", "cde"};
+     bundle_add_str_array(b, "k3", s_arr, 3); // Add a key-value pair
+     bundle_foreach(b, sample_cb, NULL);
+     bundle_free(b);
+     return 0;
+ }
+ * @endcode
  * @see bundle_foreach()
  */
 int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned int *array_len, size_t **array_element_size);
@@ -417,6 +449,7 @@ int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned
 /**
  * @brief Encodes a bundle to the bundle_raw format (uses base64 format).
  * @since_tizen 2.3
+ * @remarks The @a r should be released using free().
  * @param[in] b The bundle object
  * @param[out] r The returned bundle_raw data(byte data)
  *               @a r MUST BE FREED by free(r)
@@ -433,8 +466,8 @@ int bundle_keyval_get_array_val(bundle_keyval_t *kv, void ***array_val, unsigned
  bundle_raw *r;
  int len;
  bundle_encode(b, &r, &len); // Encode b
-
  bundle_free(b);
+ free(r);
  * @endcode
  */
 int bundle_encode(bundle *b, bundle_raw **r, int *len);