Fixed doxygen rule violations.

Change-Id: I454d07a9d6ee2f62dbb078266215f64e7cc79ba0
Signed-off-by: saerome kim <saerome.kim@samsung.com>

diff --git a/include/mtp.h b/include/mtp.h
old mode 100755 (executable)
new mode 100644 (file)
index 3574d56..e0aad34
--- a/include/mtp.h
+++ b/include/mtp.h
@@ -27,9 +27,6 @@ extern "C" {
  * @file mtp.h
  * @brief This file contains the MTP API
  */
-#ifndef TIZEN_ERROR_MTP
-#define TIZEN_ERROR_MTP -0x01CC0000
-#endif
 
 /**
  * @addtogroup CAPI_NETWORK_MTP_MANAGER_MODULE
@@ -37,19 +34,19 @@ extern "C" {
  */
 
 /**
- * @brief The handle to the mtp device
+ * @brief The handle to the mtp device.
  * @since_tizen 3.0
  */
 typedef int mtp_device_h;
 
 /**
- * @brief The handle to the mtp storage
+ * @brief The handle to the mtp storage.
  * @since_tizen 3.0
  */
 typedef int mtp_storage_h;
 
 /**
- * @brief The handle to the mtp object
+ * @brief The handle to the mtp object.
  * @since_tizen 3.0
  */
 typedef int mtp_object_h;
@@ -75,7 +72,7 @@ typedef enum {
 } mtp_error_e;
 
 /**
- * @brief Enumerations for MTP Storage type
+ * @brief Enumerations for MTP Storage type.
  * @since_tizen 3.0
  */
 typedef enum {
@@ -87,7 +84,7 @@ typedef enum {
 } mtp_storage_type_e;
 
 /**
- * @brief Enumerations for MTP file type
+ * @brief Enumerations for MTP file type.
  * @since_tizen 3.0
  */
 typedef enum {
@@ -137,12 +134,12 @@ typedef enum {
        MTP_FILETYPE_PLAYLIST, /**< PLAYLIST file type */
        MTP_FILETYPE_UNKNOWN, /**< Unknown file type */
 
-       MTP_FILETYPE_ALL, /**< Helper enum value for certain function */
-       MTP_FILETYPE_ALL_IMAGE /**< Helper enum value for certain function */
+       MTP_FILETYPE_ALL, /**< Helper enum value for all file types */
+       MTP_FILETYPE_ALL_IMAGE /**< Helper enum value for all image files types */
 } mtp_filetype_e;
 
 /**
- * @brief Enumerations for MTP event type
+ * @brief Enumerations for MTP event type.
  * @since_tizen 3.0
  */
 typedef enum {
@@ -160,14 +157,14 @@ typedef enum {
  * @brief Called when mtp event is occured.
  * @since_tizen 3.0
  * @remarks Depending on the type of event, the meaning of event parameter is different.
- * - If event is device event, then event_parameter type is mtp_device_h.
- * - If event is storage event, then event_parameter type is mtp_storage_h.
- * - If event is object event, then event_parameter type is mtp_object_h.
- * - If event is MTP_EVENT_TURNED_OFF, then event_parameter is 0.
+ * - If event is device event, then event_parameter type is #mtp_device_h.
+ * - If event is storage event, then event_parameter type is #mtp_storage_h.
+ * - If event is object event, then event_parameter type is #mtp_object_h.
+ * - If event is #MTP_EVENT_TURNED_OFF, then event_parameter is 0.
  *
- * @param [in] event The event
- * @param [in] event_parameter The event parameter
- * @param [in] user_data The user data passed from the callback registration function
+ * @param[in] event The event
+ * @param[in] event_parameter The event parameter
+ * @param[in] user_data The user data passed from the callback registration function
  *
  * @see mtp_set_mtp_event_cb()
  * @see mtp_unset_mtp_event_cb()
@@ -194,8 +191,11 @@ int mtp_initialize(void);
 /**
  * @brief Gets the mtp devices.
  * @since_tizen 3.0
- * @param [out] mtp_devices The MTP device list
- * @param [out] device_count Length of device list
+ *
+ * @remarks The @a mtp_devices should be released using free().
+ *
+ * @param[out] mtp_devices The MTP device list
+ * @param[out] device_count Length of device list
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -215,9 +215,9 @@ int mtp_get_devices(mtp_device_h **mtp_devices, int *device_count);
  * @since_tizen 3.0
  * @remarks The @a mtp_storages should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [out] mtp_storages Current mtp storage list
- * @param [out] storage_count Length of storage list
+ * @param[in] mtp_device The MTP device
+ * @param[out] mtp_storages Current mtp storage list
+ * @param[out] storage_count Length of storage list
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -238,12 +238,12 @@ int mtp_get_storages(mtp_device_h mtp_device, mtp_storage_h **mtp_storages, int*
  * @remarks The @a object_handles should be freed using free().
  * @remarks If the @a parent is 0, it means "root folder" of mtp storage.
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [in] file_type The file type what you want
- * @param [in] parent The parent object handle
- * @param [out] object_handles The object handle list
- * @param [out] object_count Length of object handle list
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[in] file_type The file type what you want
+ * @param[in] parent The parent object handle
+ * @param[out] object_handles The object handle list
+ * @param[out] object_count Length of object handle list
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -267,9 +267,9 @@ int mtp_get_object_handles(mtp_device_h mtp_device, mtp_storage_h mtp_storage, m
  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  * http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. \n
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [in] dest_path The dest path
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[in] dest_path The dest path
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -294,9 +294,9 @@ int mtp_get_object(mtp_device_h mtp_device, mtp_object_h object_handle, char *de
  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  * http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [in] dest_path The dest path
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[in] dest_path The dest path
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -324,8 +324,8 @@ int mtp_get_thumbnail(mtp_device_h mtp_device, mtp_object_h object_handle, char
  * If object state is changed, #MTP_EVENT_OBJECT_ADDED or #MTP_EVENT_OBJECT_REMOVED event is occur. \n
  * If mtp service is turned off, #MTP_EVENT_TURNED_OFF event is occur. \n
  *
- * @param [in] event_cb The callback
- * @param [in] user_data The user data
+ * @param[in] event_cb The callback
+ * @param[in] user_data The user data
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -341,7 +341,7 @@ int mtp_add_mtp_event_cb(mtp_event_cb event_cb, void *user_data);
  * @brief Removes the callback function.
  * @since_tizen 3.0
  *
- * @param [in] event_cb The callback
+ * @param[in] event_cb The callback
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -382,8 +382,8 @@ int mtp_deinitialize(void);
  * @since_tizen 3.0
  * @remarks The @a manufacturer_name should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [out] manufacturer_name The manufacturer name of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] manufacturer_name The manufacturer name of Device information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -406,8 +406,8 @@ int mtp_deviceinfo_get_manufacturer_name(mtp_device_h mtp_device, char **manufac
  * @since_tizen 3.0
  * @remarks The @a model_name should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [out] model_name The model name of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] model_name The model name of Device information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -430,8 +430,8 @@ int mtp_deviceinfo_get_model_name(mtp_device_h mtp_device, char **model_name);
  * @since_tizen 3.0
  * @remarks The @a serial_number should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [out] serial_number The serial number of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] serial_number The serial number of Device information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -454,8 +454,8 @@ int mtp_deviceinfo_get_serial_number(mtp_device_h mtp_device, char **serial_numb
  * @since_tizen 3.0
  * @remarks The @a device_version should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [out] device_version The device version of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] device_version The device version of Device information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -487,9 +487,9 @@ int mtp_deviceinfo_get_device_version(mtp_device_h mtp_device, char **device_ver
  * @since_tizen 3.0
  * @remarks The @a description should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] description The description of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] description The description of Storage information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -511,9 +511,9 @@ int mtp_storageinfo_get_description(mtp_device_h mtp_device, mtp_storage_h mtp_s
  * @brief Gets the free space of the storage information in bytes.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] free_space The free space of Storage information (bytes)
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] free_space The free space of Storage information (bytes)
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -535,9 +535,9 @@ int mtp_storageinfo_get_free_space(mtp_device_h mtp_device, mtp_storage_h mtp_st
  * @brief Gets the max capacity of the storage information in bytes.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] max_capacity The max capacity of Storage information (bytes)
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] max_capacity The max capacity of Storage information (bytes)
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -559,9 +559,9 @@ int mtp_storageinfo_get_max_capacity(mtp_device_h mtp_device, mtp_storage_h mtp_
  * @brief Gets the storage type of the storage information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] storage_type The storage type of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] storage_type The storage type of Storage information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -584,9 +584,9 @@ int mtp_storageinfo_get_storage_type(mtp_device_h mtp_device, mtp_storage_h mtp_
  * @since_tizen 3.0
  * @remarks The @a volume_identifier should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] volume_identifier The volume identifier of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] volume_identifier The volume identifier of Storage information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -618,9 +618,9 @@ int mtp_storageinfo_get_volume_identifier(mtp_device_h mtp_device, mtp_storage_h
  * @since_tizen 3.0
  * @remarks The @a file_name should be freed using free().
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_name The file name of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_name The file name of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -645,9 +645,9 @@ int mtp_objectinfo_get_file_name(mtp_device_h mtp_device, mtp_object_h object_ha
  * @remarks The @a keywords should be freed using free().
  * @remarks The keywords are separated by comma.
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] keywords The keywords of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] keywords The keywords of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -670,9 +670,9 @@ int mtp_objectinfo_get_keywords(mtp_device_h mtp_device, mtp_object_h object_han
  * @brief Gets the association desc of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] asso_desc The association description of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] asso_desc The association description of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -695,9 +695,9 @@ int mtp_objectinfo_get_association_desc(mtp_device_h mtp_device, mtp_object_h ob
  * @brief Gets the association type of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] asso_type The association type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] asso_type The association type of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -720,9 +720,9 @@ int mtp_objectinfo_get_association_type(mtp_device_h mtp_device, mtp_object_h ob
  * @brief Gets the size of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] size The size of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] size The size of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -745,9 +745,13 @@ int mtp_objectinfo_get_size(mtp_device_h mtp_device, mtp_object_h object_handle,
  * @brief Gets the parent object handle of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] parent_object_handle The parent of Object information
+ * @remarks The @a parent_object_handle should not be released.
+ * @remarks The @a parent_object_handle can be used until the MTP service stops.
+ * @remarks The @a parent_object_handle is managed by the platform when the MTP service stop.
+ *
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] parent_object_handle The parent of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -770,9 +774,13 @@ int mtp_objectinfo_get_parent_object_handle(mtp_device_h mtp_device, mtp_object_
  * @brief Gets the mtp storage of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] mtp_storage The MTP storage of Object information
+ * @remarks The @a mtp_storage should not be released.
+ * @remarks The @a mtp_storage can be used until the MTP service stops.
+ * @remarks The @a mtp_storage is managed by the platform when the MTP service stop.
+ *
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] mtp_storage The MTP storage of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -795,11 +803,11 @@ int mtp_objectinfo_get_storage(mtp_device_h mtp_device, mtp_object_h object_hand
  * @brief Gets the object created time of the object information.
  * @since_tizen 3.0
  * @remarks When interpreted as an absolute time value, \n
- * @a data_created represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
+ * @a date_created represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] date_created The object created time of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] date_created The object created time of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -822,11 +830,11 @@ int mtp_objectinfo_get_date_created(mtp_device_h mtp_device, mtp_object_h object
  * @brief Gets the object modified time of the object information.
  * @since_tizen 3.0
  * @remarks When interpreted as an absolute time value, \n
- * @a data_modified represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
+ * @a date_modified represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] date_modified The object modified time of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] date_modified The object modified time of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -849,9 +857,9 @@ int mtp_objectinfo_get_date_modified(mtp_device_h mtp_device, mtp_object_h objec
  * @brief Gets the file type of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_type The file type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_type The file type of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -874,9 +882,9 @@ int mtp_objectinfo_get_file_type(mtp_device_h mtp_device, mtp_object_h object_ha
  * @brief Gets the image bit depth of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] depth The image bit depth of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] depth The image bit depth of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -899,9 +907,9 @@ int mtp_objectinfo_get_image_bit_depth(mtp_device_h mtp_device, mtp_object_h obj
  * @brief Gets the image pixel width of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] width The image pixel width of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] width The image pixel width of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -924,9 +932,9 @@ int mtp_objectinfo_get_image_pix_width(mtp_device_h mtp_device, mtp_object_h obj
  * @brief Gets the image pixel height of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] height The image pixel height of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] height The image pixel height of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -949,9 +957,9 @@ int mtp_objectinfo_get_image_pix_height(mtp_device_h mtp_device, mtp_object_h ob
  * @brief Gets the thumbnail size of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] size The thumbnail size of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] size The thumbnail size of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -974,9 +982,9 @@ int mtp_objectinfo_get_thumbnail_size(mtp_device_h mtp_device, mtp_object_h obje
  * @brief Gets the thumbnail file type of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_type The file type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_type The file type of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -999,9 +1007,9 @@ int mtp_objectinfo_get_thumbnail_file_type(mtp_device_h mtp_device, mtp_object_h
  * @brief Gets the thumbnail pixel height of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] height The thumbnail pixel height of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] height The thumbnail pixel height of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful
@@ -1024,9 +1032,9 @@ int mtp_objectinfo_get_thumbnail_pix_height(mtp_device_h mtp_device, mtp_object_
  * @brief Gets the thumbnail pixel width of the object information.
  * @since_tizen 3.0
  *
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] width The thumbnail pixel width of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] width The thumbnail pixel width of Object information
  *
  * @return 0 on success, otherwise a negative error value.
  * @retval #MTP_ERROR_NONE Successful