documentation touchups

diff --git a/TODO b/TODO
index 289798f..df24828 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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