Fix API description

[platform/core/api/application.git] / include / app_preference.h

diff --git a/include/app_preference.h b/include/app_preference.h
index 6313ffa..478793a 100644 (file)
--- a/include/app_preference.h
+++ b/include/app_preference.h
@@ -24,6 +24,7 @@
 extern "C" {
 #endif
 
+
 /**
  * @file app_preference.h
  */
@@ -49,9 +50,7 @@ typedef enum {
 
 /**
  * @brief Called when the given key's value in the preference changes.
- *
  * @details When the @a key is added or removed, this callback function is skipped(only update can be handled).
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key in the preference
  * @param[in] user_data The user data passed from the callback registration function
@@ -68,29 +67,26 @@ typedef void (*preference_changed_cb) (const char *key, void *user_data);
 
 /**
  * @brief Called to get key string, once for each key-value pair in the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remarks You should not free the @a key returned by this function.
- *
  * @param[in] key The key of the value added to the preference
  * @param[in] value The value associated with the key
  * @param[in] user_data The user data passed from the foreach function
  * @return @c true to continue with the next iteration of the loop,
  *         otherwise @c false to break out of the loop
- * @pre                preference_foreach_item() will invoke this callback function.
- * @see                preference_foreach_item()
+ * @pre        preference_foreach_item() will invoke this callback function.
+ * @see        preference_foreach_item()
  */
 typedef bool (*preference_item_cb)(const char *key, void *user_data);
 
 
 /**
  * @brief Sets an integer value in the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to modify
  * @param[in] value  The new @c int value for the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
@@ -102,15 +98,14 @@ int preference_set_int(const char *key, int value);
 
 /**
  * @brief Gets an integer value from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to retrieve
  * @param[out] value The @c int value for the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY    Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_set_int()
@@ -120,15 +115,14 @@ int preference_get_int(const char *key, int *value);
 
 /**
  * @brief Sets a double value in the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to modify
  * @param[in] value  The new @c double value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PREFERENCE_ERROR_NONE      Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ *                     otherwise a negative error value
+ * @retval #PREFERENCE_ERROR_NONE Successful
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_get_double()
  */
@@ -137,15 +131,14 @@ int preference_set_double(const char *key, double value);
 
 /**
  * @brief Gets a double value from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to retrieve
- * @param[out] value  The @c double value associated with the given key
+ * @param[out] value The @c double value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PREFERENCE_ERROR_NONE      Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ *                     otherwise a negative error value
+ * @retval #PREFERENCE_ERROR_NONE Successful
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY    Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_set_double()
@@ -155,17 +148,15 @@ int preference_get_double(const char *key, double *value);
 
 /**
  * @brief Sets a string value in the preference.
- *
  * @details It makes a deep copy of the added string value.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to modify
- * @param[in] value  The new @c string value associated with the given key
+ * @param[in] value The new @c string value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PREFERENCE_ERROR_NONE      Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ *                     otherwise a negative error value
+ * @retval #PREFERENCE_ERROR_NONE Successful
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_get_string()
  */
@@ -174,16 +165,15 @@ int preference_set_string(const char *key, const char *value);
 
 /**
  * @brief Gets a string value from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @remarks @a value must be released using free().
  * @param[in] key The name of the key to retrieve
  * @param[out] value The @c string value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY    Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_set_string()
@@ -193,15 +183,14 @@ int preference_get_string(const char *key, char **value);
 
 /**
  * @brief Sets a boolean value in the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to modify
  * @param[in] value The new @c boolean value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PREFERENCE_ERROR_NONE      Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ *                     otherwise a negative error value
+ * @retval #PREFERENCE_ERROR_NONE Successful
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_get_boolean()
  */
@@ -210,15 +199,14 @@ int preference_set_boolean(const char *key, bool value);
 
 /**
  * @brief Gets a boolean value from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to retrieve
- * @param[out] value  The @c boolean value associated with the given key
+ * @param[out] value The @c boolean value associated with the given key
  * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PREFERENCE_ERROR_NONE      Successful
- * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ *                     otherwise a negative error value
+ * @retval #PREFERENCE_ERROR_NONE Successful
+ * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY    Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_set_boolean()
@@ -228,14 +216,13 @@ int preference_get_boolean(const char *key, bool *value);
 
 /**
  * @brief Removes any value with the given @a key from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to remove
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  */
@@ -244,16 +231,15 @@ int preference_remove(const char *key);
 
 /**
  * @brief Checks whether the given @a key exists in the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to check
- * @param[out] existing  If @c true the @a key exists in the preference,
- *                       otherwise @c false
+ * @param[out] existing If @c true the @a key exists in the preference,
+ *                         otherwise @c false
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  */
 int preference_is_existing(const char *key, bool *existing);
@@ -261,12 +247,11 @@ int preference_is_existing(const char *key, bool *existing);
 
 /**
  * @brief Removes all key-value pairs from the preference.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_remove()
  */
@@ -275,19 +260,18 @@ int preference_remove_all(void);
 
 /**
  * @brief Registers a callback function to be invoked when value of the given key in the preference changes.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to monitor
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
- * @post       preference_changed_cb() will be invoked.
+ * @post preference_changed_cb() will be invoked.
  * @see        preference_unset_changed_cb()
  * @see preference_changed_cb()
  */
@@ -296,14 +280,13 @@ int preference_set_changed_cb(const char *key, preference_changed_cb callback, v
 
 /**
  * @brief Unregisters the callback function.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] key The name of the key to monitor
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #PREFERENCE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #PREFERENCE_ERROR_NO_KEY Required key not available
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error
  * @see        preference_set_changed_cb()
@@ -313,12 +296,11 @@ int preference_unset_changed_cb(const char *key);
 
 /**
  * @brief Retrieves all key-value pairs in the preference by invoking the callback function.
- *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] callback The callback function to get key value once for each key-value pair in the preference
  * @param[in] user_data The user data to be passed to the callback function
  * @return @c 0 on success,
- *         otherwise a negative error value
+ *                     otherwise a negative error value
  * @retval #PREFERENCE_ERROR_NONE Successful
  * @retval #PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PREFERENCE_ERROR_IO_ERROR Internal I/O Error