From 94936cbcfe3f02eb65c8b91e29896604316259d8 Mon Sep 17 00:00:00 2001
From: Daniel Drake <dsd@gentoo.org>
Date: Wed, 27 Aug 2008 22:44:24 -0500
Subject: Async I/O documentation touchups

---
 libusb/io.c     | 19 ++++++++++++++-----
 libusb/libusb.h |  5 ++++-
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/libusb/io.c b/libusb/io.c
index ab36bf9..50033ca 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -231,11 +231,14 @@ if (r == 0 && actual_length == sizeof(data)) {
  * \section asynctrf Asynchronous transfers
  *
  * We can view asynchronous I/O as a 5 step process:
- * -# Allocation
- * -# Filling
- * -# Submission
- * -# Completion handling
- * -# Deallocation
+ * -# <b>Allocation</b>: allocate a libusb_transfer
+ * -# <b>Filling</b>: populate the libusb_transfer instance with information
+ *    about the transfer you wish to perform
+ * -# <b>Submission</b>: ask libusb to submit the transfer
+ * -# <b>Completion handling</b>: examine transfer results in the
+ *    libusb_transfer structure
+ * -# <b>Deallocation</b>: clean up resources
+ * 
  *
  * \subsection asyncalloc Allocation
  *
@@ -276,6 +279,12 @@ if (r == 0 && actual_length == sizeof(data)) {
  * be invoked. It is up to the callback function to determine which of the
  * above actually happened and to act accordingly.
  *
+ * The user-specified callback is passed a pointer to the libusb_transfer
+ * structure which was used to setup and submit the transfer. At completion
+ * time, libusb has populated this structure with results of the transfer:
+ * success or failure reason, number of bytes of data transferred, etc. See
+ * the libusb_transfer structure documentation for more information.
+ *
  * \subsection Deallocation
  *
  * When a transfer has completed (i.e. the callback function has been invoked),
diff --git a/libusb/libusb.h b/libusb/libusb.h
index d2b0972..fedd624 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -693,7 +693,10 @@ struct libusb_transfer;
 typedef void (*libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
 
 /** \ingroup asyncio
- * The generic USB transfer structure.
+ * The generic USB transfer structure. The user populates this structure and
+ * then submits it in order to request a transfer. After the transfer has
+ * completed, the library populates the transfer with the results and passes
+ * it back to the user.
  */
 struct libusb_transfer {
 	/** Handle of the device that this transfer will be submitted to */
-- 
cgit v1.2.1