Fix minor documentation issues

 - Fixed few typos
 - Moved ERROR_NONE to be the first on error list
 - Removed unreturned PERMISSION_DENIED error descriptions
 - Added missing INVALID_PARAMETER error description

Change-Id: I5ce5503ca05b797e748342d896919a18e012aaa1
Signed-off-by: Paweł Szewczyk <p.szewczyk@samsung.com>

diff --git a/include/usb_host.h b/include/usb_host.h
index 1000b654cd0a49633dcb8407a404c910b7738d0c..6c301ee1ac338352b83a61f5d68a0aa3a211ac77 100755 (executable)
--- a/include/usb_host.h
+++ b/include/usb_host.h
@@ -206,8 +206,8 @@ int usb_host_create(usb_host_context_h *ctx);
  * @since_tizen 3.0
  * @param[in] ctx Context to deinitialize
  * @return 0 on success, otherwise a negative error value
- * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @retval #USB_HOST_ERROR_NONE Success
+ * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @pre Context must be initialized by usb_host_create().
  */
 int usb_host_destroy(usb_host_context_h ctx);
@@ -234,11 +234,10 @@ int usb_host_destroy(usb_host_context_h ctx);
  * @param[out] devs An array of devices
  * @param[out] length Number of devices
  * @return 0 on success, otherwise a negative error value
+ * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_OUT_OF_MEMORY Out of memory
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Operation not supported
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_NONE Successful
  * @post @a devs must be freed with usb_host_free_device_list() when no longer needed.
  */
 int usb_host_get_device_list(usb_host_context_h ctx, usb_host_device_h **devs, int *length);
@@ -253,8 +252,8 @@ int usb_host_get_device_list(usb_host_context_h ctx, usb_host_device_h **devs, i
  * @param[in] devs List of devices
  * @param[in] unref_devices Set to true to unreference devices, set to false to not unref
  * @return 0 on success, otherwise a negative error value
- * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @retval #USB_HOST_ERROR_NONE Successful
+ * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @pre usb_host_get_device_list() must be called before using this function.
  */
 int usb_host_free_device_list(usb_host_device_h *devs, bool unref_devices);
@@ -266,8 +265,8 @@ int usb_host_free_device_list(usb_host_device_h *devs, bool unref_devices);
  * @since_tizen 3.0
  * @param[in] dev Device to reference
  * @return 0 on success, error code otherwise
- * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @retval #USB_HOST_ERROR_NONE Successful
+ * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  */
 int usb_host_ref_device(usb_host_device_h dev);
 
@@ -310,9 +309,9 @@ int usb_host_device_open(usb_host_device_h dev);
  * @since_tizen 3.0
  * @param[in] dev Device that should be closed
  * @return 0 on success, otherwise a negative error value
+ * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_DEVICE_NOT_OPENED If device is not opened
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_NONE Successful
  */
 int usb_host_device_close(usb_host_device_h dev);
 
@@ -348,7 +347,6 @@ int usb_host_device_open_with_vid_pid(usb_host_context_h ctx,
  * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  */
 int usb_host_device_get_bus_number(usb_host_device_h dev, int *bus_number);
 
@@ -412,9 +410,9 @@ int usb_host_device_get_config(usb_host_device_h dev, int config_index, usb_host
  * @param[in] dev A device
  * @param[out] config Handle to active configuration
  * @return 0 on success, otherwise a negative error value
+ * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_NO_SUCH_DEVICE the dev has been disconnected
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_DEVICE_NOT_OPENED The device was not opened
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @post Obtained configuration should be destroyed by usb_host_config_destroy()
@@ -448,7 +446,8 @@ int usb_host_set_config(usb_host_config_h configuration);
  * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_RESOURCE_BUSY Interfaces are currently claimed
- * @retval #USB_HOST_ERROR_NO_SUCH_DEVICE Device has been disconnected
+ * @retval #USB_HOST_ERROR_NO_SUCH_DEVICE Device has beed disconnected
+ * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  */
 int usb_host_device_unconfigure(usb_host_device_h dev);
 
@@ -465,7 +464,6 @@ int usb_host_device_unconfigure(usb_host_device_h dev);
  * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  */
 int usb_host_device_get_bcd_usb(usb_host_device_h dev, int *bcd_usb);
 
@@ -598,7 +596,6 @@ int usb_host_is_device_opened(usb_host_device_h dev, bool *is_opened);
  * @retval #USB_HOST_ERROR_OVERFLOW There was no space in buffer
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  * @pre dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
  */
 int usb_host_device_get_manufacturer_str(usb_host_device_h dev, int *length, unsigned char *data);
@@ -615,7 +612,6 @@ int usb_host_device_get_manufacturer_str(usb_host_device_h dev, int *length, uns
  * @retval #USB_HOST_ERROR_OVERFLOW There was no space in buffer
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  * @pre dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
  */
 int usb_host_device_get_product_str(usb_host_device_h dev, int *length, unsigned char *data);
@@ -632,7 +628,6 @@ int usb_host_device_get_product_str(usb_host_device_h dev, int *length, unsigned
  * @retval #USB_HOST_ERROR_OVERFLOW There was no space in buffer
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  * @pre dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
  */
 int usb_host_device_get_serial_number_str(usb_host_device_h dev, int *length, unsigned char *data);
@@ -724,7 +719,6 @@ int usb_host_device_get_config_str(usb_host_config_h config, int *length, unsign
  * @retval #USB_HOST_ERROR_NOT_FOUND Configuration does not exist
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  */
 int usb_host_config_get_interface(usb_host_config_h config, int interface_index, usb_host_interface_h *interface);
 
@@ -737,7 +731,6 @@ int usb_host_config_get_interface(usb_host_config_h config, int interface_index,
  * @return 0 on success, otherwise a negative error value
  * @retval #USB_HOST_ERROR_NONE Successful
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  * @pre config must be obtained by usb_host_device_get_config().
  */
 int usb_host_config_destroy(usb_host_config_h config);
@@ -777,7 +770,6 @@ int usb_host_claim_interface(usb_host_interface_h interface, bool force);
  * @retval #USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
  * @retval #USB_HOST_ERROR_DEVICE_NOT_OPENED The device was not opened
  * @retval #USB_HOST_ERROR_NOT_SUPPORTED Not supported
- * @retval #USB_HOST_ERROR_PERMISSION_DENIED Permission denied
  */
 int usb_host_release_interface(usb_host_interface_h interface);
 
@@ -1026,7 +1018,7 @@ int usb_host_transfer(usb_host_endpoint_h ep, unsigned char *data, int length,
 
 /**
  * @ingroup CAPI_USB_HOST_HOTPLUG_MODULE
- * @brief Registers a callback function to be invoked when a device is connected or disconnected.
+ * @brief Sets a callback function to be invoked when a device is connected or disconnected.
  * @since_tizen 4.0
  * @param[in] ctx Context handle
  * @param[in] cb The callback function to be registered
@@ -1043,7 +1035,7 @@ int usb_host_set_hotplug_cb(usb_host_context_h ctx, usb_host_hotplug_cb cb, usb_
 
 /**
  * @ingroup CAPI_USB_HOST_HOTPLUG_MODULE
- * @brief Unregisters the hotplug callback function.
+ * @brief Unsets the hotplug callback function.
  * @since_tizen 4.0
  * @param[in] handle Handle of the callback to be unregistered
  * @return 0 on success, negative error code on error