documentation touchups

6 files changed, 37 insertions, 21 deletions

diff --git a/TODO b/TODO
index 289798f..df24828 100644
--- a/TODO
+++ b/TODO
@@ -3,7 +3,6 @@ for 1.0
 fixme review
 review functionality missing over 0.1
 endianness of control setup, issues when resubmitting transfers
-doxygen warnings
 serialization of handle_events
 internal docs for OS porters
 
diff --git a/libusb/core.c b/libusb/core.c
index 6a9e9a6..cba14cb 100644
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -468,6 +468,7 @@ API_EXPORTED uint8_t libusb_get_device_address(libusb_device *dev)
  * endpoint. This is useful for setting up isochronous transfers.
  *
  * \param dev a device
+ * \param endpoint address of the endpoint in question
  * \returns the wMaxPacketSize value, or LIBUSB_ERROR_NOT_FOUND if the endpoint
  * does not exist.
  */
@@ -778,8 +779,8 @@ out:
  * \param dev a device handle
  * \param interface_number the <tt>bInterfaceNumber</tt> of the
  * previously-claimed interface
- * \param altsetting the <tt>bAlternateSetting</tt> of the alternate setting
- * to activate
+ * \param alternate_setting the <tt>bAlternateSetting</tt> of the alternate
+ * setting to activate
  * \returns 0 on success
  * \returns LIBUSB_ERROR_NOT_FOUND if the interface was not claimed, or the
  * requested alternate setting does not exist
diff --git a/libusb/descriptor.c b/libusb/descriptor.c
index 31401cc..72c6d7e 100644
--- a/libusb/descriptor.c
+++ b/libusb/descriptor.c
@@ -140,19 +140,19 @@ static int parse_endpoint(struct libusb_endpoint_descriptor *endpoint,
 	len = (int)(buffer - begin);
 	if (!len) {
 		endpoint->extra = NULL;
-		endpoint->extralen = 0;
+		endpoint->extra_length = 0;
 		return parsed;
 	}
 
 	extra = malloc(len);
 	endpoint->extra = extra;
 	if (!extra) {
-		endpoint->extralen = 0;
+		endpoint->extra_length = 0;
 		return LIBUSB_ERROR_NO_MEM;
 	}
 
 	memcpy(extra, begin, len);
-	endpoint->extralen = len;
+	endpoint->extra_length = len;
 
 	return parsed;
 }
@@ -211,7 +211,7 @@ static int parse_interface(struct libusb_interface *interface,
 		interface->num_altsetting++;
 		usbi_parse_descriptor(buffer, "bbbbbbbbb", ifp);
 		ifp->extra = NULL;
-		ifp->extralen = 0;
+		ifp->extra_length = 0;
 		ifp->endpoint = NULL;
 
 		/* Skip over the interface */
@@ -252,7 +252,7 @@ static int parse_interface(struct libusb_interface *interface,
 				goto err;
 			}
 			memcpy((unsigned char *) ifp->extra, begin, len);
-			ifp->extralen = len;
+			ifp->extra_length = len;
 		}
 
 		/* Did we hit an unexpected descriptor? */
@@ -361,7 +361,7 @@ int usbi_parse_configuration(struct libusb_config_descriptor *config,
 	size -= config->bLength;
 
 	config->extra = NULL;
-	config->extralen = 0;
+	config->extra_length = 0;
 
 	for (i = 0; i < config->bNumInterfaces; i++) {
 		int len;
@@ -397,7 +397,7 @@ int usbi_parse_configuration(struct libusb_config_descriptor *config,
 		len = (int)(buffer - begin);
 		if (len) {
 			/* FIXME: We should realloc and append here */
-			if (!config->extralen) {
+			if (!config->extra_length) {
 				config->extra = malloc(len);
 				if (!config->extra) {
 					r = LIBUSB_ERROR_NO_MEM;
@@ -405,7 +405,7 @@ int usbi_parse_configuration(struct libusb_config_descriptor *config,
 				}
 
 				memcpy((unsigned char *) config->extra, begin, len);
-				config->extralen = len;
+				config->extra_length = len;
 			}
 		}
 
diff --git a/libusb/io.c b/libusb/io.c
index 65a7b95..04ffc6e 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -396,7 +396,7 @@ if (r == 0 && actual_length == sizeof(data)) {
  *
  * The data for each packet will be found at an offset into the buffer that
  * can be calculated as if each prior packet completed in full. The
- * libusb_get_iso_packet_offset() and libusb_get_iso_packet_offset_simple()
+ * libusb_get_iso_packet_buffer() and libusb_get_iso_packet_buffer_simple()
  * functions may help you here.
  *
  * \section asyncmem Memory caveats
diff --git a/libusb/libusb.h b/libusb/libusb.h
index 97b3847..3f04e91 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -142,7 +142,8 @@ enum libusb_transfer_type {
 	LIBUSB_TRANSFER_TYPE_INTERRUPT = 3,
 };
 
-/** Standard requests, as defined in table 9-3 of the USB2 specifications */
+/** \ingroup misc
+ * Standard requests, as defined in table 9-3 of the USB2 specifications */
 enum libusb_standard_request {
 	/** Request status of the specific recipient */
 	LIBUSB_REQUEST_GET_STATUS = 0x00,
@@ -346,11 +347,19 @@ struct libusb_endpoint_descriptor {
 	/** Interval for polling endpoint for data transfers. */
 	uint8_t  bInterval;
 
+	/** For audio devices only: the rate at which synchronization feedback
+	 * is provided. */
 	uint8_t  bRefresh;
+
+	/** For audio devices only: the address if the synch endpoint */
 	uint8_t  bSynchAddress;
 
-	const unsigned char *extra;	/* Extra descriptors */
-	int extralen;
+	/** Extra descriptors. If libusb encounters unknown endpoint descriptors,
+	 * it will store them here, should you wish to parse them. */
+	const unsigned char *extra;
+
+	/** Length of the extra descriptors, in bytes. */
+	int extra_length;
 };
 
 /** \ingroup desc
@@ -395,8 +404,12 @@ struct libusb_interface_descriptor {
 	 * by the bNumEndpoints field. */
 	const struct libusb_endpoint_descriptor *endpoint;
 
-	const unsigned char *extra;	/* Extra descriptors */
-	int extralen;
+	/** Extra descriptors. If libusb encounters unknown interface descriptors,
+	 * it will store them here, should you wish to parse them. */
+	const unsigned char *extra;
+
+	/** Length of the extra descriptors, in bytes. */
+	int extra_length;
 };
 
 /** \ingroup desc
@@ -449,8 +462,12 @@ struct libusb_config_descriptor {
 	 * this array is determined by the bNumInterfaces field. */
 	const struct libusb_interface *interface;
 
-	const unsigned char *extra;	/* Extra descriptors */
-	int extralen;
+	/** Extra descriptors. If libusb encounters unknown configuration
+	 * descriptors, it will store them here, should you wish to parse them. */
+	const unsigned char *extra;
+
+	/** Length of the extra descriptors, in bytes. */
+	int extra_length;
 };
 
 /** \ingroup asyncio
diff --git a/libusb/sync.c b/libusb/sync.c
index 6f1f07b..c2790fb 100644
--- a/libusb/sync.c
+++ b/libusb/sync.c
@@ -41,7 +41,6 @@ static void ctrl_transfer_cb(struct libusb_transfer *transfer)
 	/* caller interprets result and frees transfer */
 }
 
-/* FIXME: does this support partial transfers? */
 /** \ingroup syncio
  * Perform a USB control transfer. The direction of the transfer is inferred
  * from the bmRequestType field of the setup packet.
@@ -58,7 +57,7 @@ static void ctrl_transfer_cb(struct libusb_transfer *transfer)
  * \param timeout timeout (in millseconds) that this function should wait
  * before giving up due to no response being received. For no timeout, use
  * value 0.
- * \returns 0 on success
+ * \returns on success, the number of bytes actually transferred
  * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
  * \returns LIBUSB_ERROR_PIPE if the control request was not supported by the
  * device