storage-expand: Update description of storage-expand APIs

Update description of storage-expand APIs in @brief, @details, @remarks, and @code
to supplement the explanation.

Change-Id: If76a188a49b62d49642f5fc5f9cf3bdce0f5592d
Signed-off-by: Unsung Lee <unsung.lee@samsung.com>

diff --git a/include/storage-expand.h b/include/storage-expand.h
index 698e360b3535d733abba0f7e7b2858ff3efeee40..c5f719b530bed0f96174208746fed4a52ee6b101 100644 (file)
--- a/include/storage-expand.h
+++ b/include/storage-expand.h
@@ -70,7 +70,9 @@ typedef enum {
 
 /**
  * @brief Called to get information once for each supported storage.
+ * @details Called up to the maximum number of supported storages to get information.
  * @since_tizen 2.3
+ * @remarks Defined by the storage_foreach_device_supported() caller.
  * @param[in] storage_id The unique storage ID
  * @param[in] type The type of the storage
  * @param[in] state The current state of the storage
@@ -80,23 +82,32 @@ typedef enum {
  *         otherwise @c false to break out of the loop
  * @pre        storage_foreach_device_supported() will invoke this callback function.
  * @see        storage_foreach_device_supported()
+ * @code
+ *      my_storage_device_supported_cb(int storage_id, storage_type_e type,
+ *              storage_state_e state, const char *path, void *user_data) {
+ *              return true;
+ *      }
+ *
+ *      storage_foreach_device_supported(my_storage_device_supported_cb, NULL);
+ * @endcode
  */
 typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type,
                storage_state_e state, const char *path, void *user_data);
 
 
 /**
- * @brief Retrieves all the storage in a device.
- * @details This function invokes the callback function once for each storage in a device. \n
+ * @brief Retrieves all the storage in a device using a callback function.
+ * @details Invokes the callback function once for each storage in a device. \n
  *          If storage_device_supported_cb() returns @c false, then the iteration will be finished.
  * @since_tizen 2.3
+ * @remarks A callback function should be defined by this function caller.
  * @param[in] callback The iteration callback function
  * @param[in] user_data The user data to be passed to the callback function
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #STORAGE_ERROR_NONE Successful
  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
- * @post This function invokes storage_device_supported_cb() repeatedly for each supported device.
+ * @post Invokes storage_device_supported_cb() repeatedly for each supported device.
  * @see storage_device_supported_cb()
  */
 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
@@ -104,6 +115,7 @@ int storage_foreach_device_supported(storage_device_supported_cb callback, void
 
 /**
  * @brief Gets the absolute path to the root directory of the given storage.
+ * @details Determines root directory of internal or external storage using storage_id.
  * @since_tizen 2.3
  * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
  *          When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
@@ -121,6 +133,12 @@ int storage_foreach_device_supported(storage_device_supported_cb callback, void
  * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
  * @see storage_get_state()
+ * @code
+ *      int storage_id = 0;
+ *      char path[100];
+ *
+ *      storage_get_root_directory(storage_id, &path)
+ * @endcode
  */
 int storage_get_root_directory(int storage_id, char **path);
 
@@ -145,6 +163,7 @@ typedef enum {
 
 /**
  * @brief Gets the absolute path to the each directory of the given storage.
+ * @details Gets absolute path among several directories defined in the storage_directory_e.
  * @since_tizen 2.3
  * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
  *          When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
@@ -164,13 +183,21 @@ typedef enum {
  * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
  * @see storage_get_state()
+ * @code
+ *      int storage_id = 0;
+ *      char path[100];
+ *
+ *      storage_get_directory(storage_id, STORAGE_DIRECTORY_IMAGES, &path)
+ * @endcode
  */
 int storage_get_directory(int storage_id, storage_directory_e type, char **path);
 
 
 /**
- * @brief Gets the type of the given storage.
+ * @brief Gets the type (such as internal or external) of the given storage.
+ * @details Gets the storage type among defined in the storage_type_e using storage_id.
  * @since_tizen 2.3
+ * @remarks Determines whether it is an internal or external storage using the input storage_id.
  * @param[in] storage_id The storage device
  * @param[out] type The type of the storage
  * @return @c 0 on success,
@@ -180,13 +207,21 @@ int storage_get_directory(int storage_id, storage_directory_e type, char **path)
  * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #STORAGE_ERROR_NOT_SUPPORTED Storage not supported
  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
+ * @code
+ *      int storage_id = 0;
+ *      storage_type_e type;
+ *
+ *      storage_get_type(storage_id, &type);
+ * @endcode
  */
 int storage_get_type(int storage_id, storage_type_e *type);
 
 
 /**
- * @brief Gets the current state of the given storage.
+ * @brief Gets the current mounted state of storage corresponding to the specified id.
+ * @details Gets the storage mounted state among defined in the storage_state_e using storage_id.
  * @since_tizen 2.3
+ * @remarks Determines whether it is an internal or external storage using the input storage_id.
  * @param[in] storage_id The storage device
  * @param[out] state The current state of the storage
  * @return @c 0 on success,
@@ -199,26 +234,44 @@ int storage_get_type(int storage_id, storage_type_e *type);
  * @see storage_get_root_directory()
  * @see storage_get_total_space()
  * @see storage_get_available_space()
+ * @code
+ *      int storage_id = 0;
+ *      storage_state_e state;
+ *
+ *      storage_get_state(storage_id, &state);
+ * @endcode
  */
 int storage_get_state(int storage_id, storage_state_e *state);
 
 
 /**
- * @brief Called when the state of storage changes.
+ * @brief Called every time when the state of specific storage changes.
+ * @details Called every time the state of a specific storage changes,
+ *          and when it is called, it retrieves the id and state of the storage.
  * @since_tizen 2.3
+ * @remarks Defined by the storage_set_state_changed_cb() and
+ *          storage_unset_state_changed_cb() caller.
  * @param[in] storage_id The unique storage ID
  * @param[in] state The current state of the storage
  * @param[in] user_data The user data passed from the foreach function
  * @pre        storage_set_state_changed_cb() will invoke this callback function.
  * @see        storage_set_state_changed_cb()
  * @see        storage_unset_state_changed_cb()
+ * @code
+ *      my_storage_state_changed_cb(int storage_id, storage_state_e state, void *user_data) {
+ *      }
+ *
+ *      storage_set_state_changed_cb(0, my_storage_state_changed_cb, NULL);
+ * @endcode
  */
 typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data);
 
 
 /**
- * @brief Registers a callback function to be invoked when the state of the storage changes.
+ * @brief Registers a callback function to be invoked when the state of the specific storage changes.
+ * @details Invokes the callback function each time for a specific storage whose state changes.
  * @since_tizen 2.3
+ * @remarks A callback function should be defined by this function caller.
  * @param[in] storage_id The storage device
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
@@ -236,8 +289,10 @@ int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callba
 
 
 /**
- * @brief Unregisters the callback function.
+ * @brief Unregisters the callback function to stop calling the callback.
+ * @details Prevents the callback function from being called any further.
  * @since_tizen 2.3
+ * @remarks A callback function should be defined by this function caller.
  * @param[in] storage_id The storage device to monitor
  * @param[in] callback The callback function to register
  * @return @c 0 on success,
@@ -264,8 +319,11 @@ typedef enum {
 
 
 /**
- * @brief Called when the state of a storage type changes.
+ * @brief Called each time when the state of a specific storage type changes.
+ * @details Called every time the state of specific storage type changes.
  * @since_tizen 3.0
+ * @remarks Defined by the storage_set_changed_cb() and
+ *          storage_unset_changed_cb() caller.
  * @param[in] storage_id The unique storage ID
  * @param[in] dev The type of the external storage device
  * @param[in] state The state of the storage
@@ -278,6 +336,14 @@ typedef enum {
  * @pre        storage_set_changed_cb() will invoke this callback function.
  * @see        storage_set_changed_cb()
  * @see        storage_unset_changed_cb()
+ * @code
+ *      my_storage_changed_cb(int storage_id, storage_dev_e dev, storage_state_e state,
+ *                const char *fstype, const char *fsuuid, const char *mountpath,
+ *                bool primary, int flags, void *user_data) {
+ *      }
+ *
+ *      storage_set_changed_cb(STORAGE_TYPE_EXTERNAL, my_storage_changed_cb, NULL);
+ * @endcode
  */
 typedef void (*storage_changed_cb)(int storage_id,
                storage_dev_e dev, storage_state_e state,
@@ -287,7 +353,9 @@ typedef void (*storage_changed_cb)(int storage_id,
 
 /**
  * @brief Registers a callback function to be invoked when the state of the specified storage device type changes.
+ * @details Invokes the callback function each time for specific storage type whose state changes.
  * @since_tizen 3.0
+ * @remarks A callback function should be defined by this function caller.
  * @param[in] type The type of the storage device
  * @param[in] callback The callback function to register
  * @param[in] user_data The user data to be passed to the callback function
@@ -306,7 +374,9 @@ int storage_set_changed_cb(storage_type_e type, storage_changed_cb callback, voi
 
 /**
  * @brief Unregisters the callback function for storage type state changes.
+ * @details Prevents the callback function from being called any further.
  * @since_tizen 3.0
+ * @remarks A callback function should be defined by this function caller.
  * @param[in] type The type of the the storage device
  * @param[in] callback The callback function to unregister
  * @return @c 0 on success,
@@ -322,8 +392,10 @@ int storage_unset_changed_cb(storage_type_e type, storage_changed_cb callback);
 
 
 /**
- * @brief Gets the total space of the given storage in bytes.
+ * @brief Gets the total space of the given storage in bytes using id.
+ * @details Finds target storage using storage_id and gets the total space of a storage in bytes.
  * @since_tizen 2.3
+ * @remarks Determines whether it is an internal or external storage using the input storage_id.
  * @param[in] storage_id The storage device
  * @param[out] bytes The total space size of the storage (bytes)
  * @return @c 0 on success,
@@ -335,13 +407,21 @@ int storage_unset_changed_cb(storage_type_e type, storage_changed_cb callback);
  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
  * @see storage_get_state()
  * @see storage_get_available_space()
+ * @code
+ *      int storage_id = 0;
+ *      unsigned long long bytes;
+ *
+ *      storage_get_total_space(storage_id, &bytes);
+ * @endcode
  */
 int storage_get_total_space(int storage_id, unsigned long long *bytes);
 
 
 /**
  * @brief Gets the available space size of the given storage in bytes.
+ * @details Gets the available space of a storage in bytes using storage_id.
  * @since_tizen 2.3
+ * @remarks Determines whether it is an internal or external storage using the input storage_id.
  * @param[in] storage_id The storage device
  * @param[out] bytes The available space size of the storage (bytes)
  * @return @c 0 on success,
@@ -353,17 +433,23 @@ int storage_get_total_space(int storage_id, unsigned long long *bytes);
  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
  * @see storage_get_state()
  * @see storage_get_total_space()
+ * @code
+ *      int storage_id = 0;
+ *      unsigned long long bytes;
+ *
+ *      storage_get_available_space(storage_id, &bytes);
+ * @endcode
  */
 int storage_get_available_space(int storage_id, unsigned long long *bytes);
 
 
 /**
  * @brief Gets the type and the kind of external device for the given storage id.
- *
+ * @details Gets the external storage type defined in storage_type_e and kind
+ *          defined in storage_dev_e using storage_id.
  * @since_tizen 5.0
- *
- * @remarks This function works only for external storages.
- * If @a type is #STORAGE_TYPE_INTERNAL, this function returns #STORAGE_ERROR_INVALID_PARAMETER and @a dev is unchanged.
+ * @remarks Works solely on external storages, not internal storages.
+ *          If @a type is #STORAGE_TYPE_INTERNAL, this function returns #STORAGE_ERROR_INVALID_PARAMETER and @a dev is unchanged.
  *
  * @param[in] storage_id The storage id
  * @param[out] type The storage @a type (internal or external). If @a type is #STORAGE_TYPE_INTERNAL, this function returns #STORAGE_ERROR_INVALID_PARAMETER and @a dev is unchanged.
@@ -377,6 +463,13 @@ int storage_get_available_space(int storage_id, unsigned long long *bytes);
  * @retval #STORAGE_ERROR_OUT_OF_MEMORY      Out of memory
  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
+ * @code
+ *      int storage_id = 0;
+ *      storage_type_e type;
+ *      storage_dev_e dev;
+ *
+ *      storage_get_type_dev(storage_id, &type, &dev);
+ * @endcode
  */
 int storage_get_type_dev(int storage_id, storage_type_e *type, storage_dev_e *dev);