* \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
*
* 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),
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 */