From: Daniel Drake <dsd@gentoo.org>
Date: Sun, 27 Apr 2008 18:53:51 +0000 (+0100)
Subject: Documentation touchups
X-Git-Tag: upstream/1.0.21~1097
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3bdafaa359d9c65e1af360b5338e1f25528a8066;p=platform%2Fupstream%2Flibusb.git

Documentation touchups

Detail that interrupt polling interval is fixed to endpoint bInterval,
and that data may be transferred even on a timeout condition.
---

diff --git a/libusb/io.c b/libusb/io.c
index 18ab594..48ffce7 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -332,6 +332,11 @@ if (r == 0 && actual_length == sizeof(data)) {
  * and libusb_control_transfer_get_setup() functions within your transfer
  * callback.
  *
+ * \section asyncintr Considerations for interrupt transfers
+ * 
+ * All interrupt transfers are performed using the polling interval presented
+ * by the bInterval value of the endpoint descriptor.
+ *
  * \section asynciso Considerations for isochronous transfers
  *
  * As isochronous transfers are more complicated than transfers to
diff --git a/libusb/sync.c b/libusb/sync.c
index b2b564d..e7d7369 100644
--- a/libusb/sync.c
+++ b/libusb/sync.c
@@ -177,11 +177,25 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
 	return r;
 }
 
-/* FIXME: document timeout handling vs URB splitting */
 /** \ingroup syncio
  * Perform a USB bulk transfer. The direction of the transfer is inferred from
  * the direction bits of the endpoint address.
  *
+ * For bulk reads, the <tt>length</tt> field indicates the maximum length of
+ * data you are expecting to receive. If less data arrives than expected,
+ * this function will return that data, so be sure to check the
+ * <tt>transferred</tt> output parameter.
+ *
+ * You should also check the <tt>transferred</tt> parameter for bulk writes.
+ * Not all of the data may have been written.
+ *
+ * Also check <tt>transferred</tt> when dealing with a timeout error code.
+ * libusb may have to split your transfer into a number of chunks to satisfy
+ * underlying O/S requirements, meaning that the timeout may expire after
+ * the first few chunks have completed. libusb is careful not to lose any data
+ * that may have been transferred; do not assume that timeout conditions
+ * indicate a complete lack of I/O.
+ *
  * \param dev_handle a handle for the device to communicate with
  * \param endpoint the address of a valid endpoint to communicate with
  * \param data a suitably-sized data buffer for either input or output
@@ -195,7 +209,8 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
  * value 0.
  *
  * \returns 0 on success (and populates <tt>transferred</tt>)
- * \returns -ETIMEDOUT if the transfer timed out
+ * \returns -ETIMEDOUT if the transfer timed out (and populates
+ * <tt>transferred</tt>)
  * \returns other negative code on error
  */
 API_EXPORTED int libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
@@ -206,11 +221,27 @@ API_EXPORTED int libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
 		transferred, timeout, LIBUSB_ENDPOINT_TYPE_BULK);
 }
 
-/* FIXME: do we need an interval param here? usbfs doesn't expose it? */
 /** \ingroup syncio
  * Perform a USB interrupt transfer. The direction of the transfer is inferred
  * from the direction bits of the endpoint address.
  *
+ * For interrupt reads, the <tt>length</tt> field indicates the maximum length
+ * of data you are expecting to receive. If less data arrives than expected,
+ * this function will return that data, so be sure to check the
+ * <tt>transferred</tt> output parameter.
+ *
+ * You should also check the <tt>transferred</tt> parameter for interrupt
+ * writes. Not all of the data may have been written.
+ *
+ * Also check <tt>transferred</tt> when dealing with a timeout error code.
+ * libusb may have to split your transfer into a number of chunks to satisfy
+ * underlying O/S requirements, meaning that the timeout may expire after
+ * the first few chunks have completed. libusb is careful not to lose any data
+ * that may have been transferred; do not assume that timeout conditions
+ * indicate a complete lack of I/O.
+ *
+ * The default endpoint bInterval value is used as the polling interval.
+ *
  * \param dev_handle a handle for the device to communicate with
  * \param endpoint the address of a valid endpoint to communicate with
  * \param data a suitably-sized data buffer for either input or output