Ticket #1740: USB3_sample2_definitions.diff

drivers/USB3.dox

@@ -16 +16 @@
 
 /*! 
   \typedef struct usb_module_info usb_module_info
-  \brief The main interface object. See the usb_module_info documentation.
+  \brief This is the main interface object. See the usb_module_info documentation.
 */
 
 /*!
   \typedef uint32 usb_id
-  \brief Uniquely identify various USB objects that are used in the module.
+  \brief uniquely identifies various USB objects that are used in the module
 */
 
 /*!
   \typedef usb_id usb_device
-  \brief Uniquely identify USB devices.
+  \brief uniquely identifies USB devices
 */
 
 /*!
   \typedef usb_id usb_interface
-  \brief Uniquely identify USB interfaces.
+  \brief uniquely identifies USB interfaces
 */
 
 /*!
   \typedef usb_id usb_pipe
-  \brief Uniquely identify USB pipes.
+  \brief uniquely identifies USB pipes
 */
 
 /*!
   \typedef struct usb_endpoint_info usb_endpoint_info
-  \brief Container for USB endpoint descriptors.
-  \see Documentation for usb_endpoint_info.
+  \brief container for USB endpoint descriptors
+  \see documentation for usb_endpoint_info
 */
 
 /*!
   \typedef struct usb_interface_info usb_interface_info
   \brief Container for USB interface descriptors.
-  \see Documentation for usb_interface_info.
+  \see documentation for usb_interface_info
 */
 
 /*!
-  \typedef usb_interface_list usb_interface_list
+  \typedef struct usb_interface_list usb_interface_list
   \brief Container that holds a list of USB interface descriptors.
-  \see Documentation for usb_interface_list.
+  \see documentation for usb_interface_list
 */
 
 /*!
   \typedef struct usb_configuration_info usb_configuration_info
   \brief Container for USB configuration descriptors.
-  \see Documentation for usb_configuration_info.
+  \see documentation for usb_configuration_info
 */
 
 ///// usb_notify_hooks /////
 
 /*!
   \struct usb_notify_hooks
-  \brief Hooks that the USB stack can callback in case of events.
+  \brief hooks that the USB stack can callback in case of events
 */
 
 /*!
   \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie)
-  \brief Called by the stack in case a device is added.
+  \brief called by the stack in case a device is added
   
-  As soon as you have registered hooks using the 
+  Once you have registered hooks using the 
   usb_module_info::install_notify() method, this hook will be called as soon as
   a device is inserted that matches your provided usb_support_descriptor.
   
-  \param device A unique id that identifies this USB device.
+  \param device a unique id that identifies this USB device
   \param[in] cookie You can store a pointer to an object in this variable.
     When the device is removed, this cookie will be provided to you.
   \return You should return \c B_OK in case of success. The USB stack will then
-    request the kernel to republish your device names, so that the new device
+    request the kernel to republish your device names so that the new device
     will be shown in the \c /dev tree. If you return an error value, the 
     \a device id will become invalid and you will not be notified if this
     device is removed.
@@ -91 +91 @@
 
 /*!
   \var status_t (*usb_notify_hooks::device_removed)(void *cookie)
-  \brief Called by the stack in case a device you are using is removed.
+  \brief called by the stack in case a device you are using is removed
   
   If you have accepted a device in the device_added() hook, this hook will
   be called as soon as the device is removed.
   
-  \param cookie The cookie you provided in the device_added() hook. Make sure
-    that you free the cookie, if necessary.
+  \param cookie This is the cookie you provided in the device_added() hook. Make sure
+    that you free the cookie if necessary.
   \return Currently the return value of this hook is ignored. It is recommended
     to return \c B_OK though.
 */
@@ -106 +106 @@
   
 /*!
   \struct usb_support_descriptor
-  \brief Description of device descriptor that the driver can handle.
+  \brief description of device descriptor that the driver can handle
   
-  Support descriptors can be used to match any form of class, subclass or
-  protocol, or a vendor and/or product. If any field has the value \c 0, it
-  is treated as a wildcard.
+  Support descriptors can be used to match any form of class, subclass, or
+  protocol, or they can be used to match a vendor and/or product.
+  If any field has the value \c 0, it is treated as a wildcard.
   
   For example, if you want to watch for all the hubs, which have a device
   class of \c 0x09, you would pass this descriptor:
@@ -125 +125 @@
   
 /*!
   \var usb_support_descriptor::dev_class
-  \brief The supported device classes.
+  \brief the supported device classes
 */
 
 /*!
   \var usb_support_descriptor::dev_subclass
-  \brief The suported device subclasses.
+  \brief the supported device subclasses
 */
 
 /*!
   \var usb_support_descriptor::dev_protocol
-  \brief The supported device protocols.
+  \brief the supported device protocols
 */
 
 /*!
   \var usb_support_descriptor::vendor
-  \brief The supported device vendor.
+  \brief the supported device vendor
 */
 
 /*!
   \var usb_support_descriptor::product
-  \brief The supported device products.
+  \brief the supported device products
 */
 
 ///// usb_endpoint_info /////
 
 /*!
   \struct usb_endpoint_info
-  \brief Container for endpoint descriptors and their Haiku USB stack
-    identifiers.
+  \brief a container for endpoint descriptors and their Haiku USB stack
+    identifiers
 */
 
 /*!
   \var usb_endpoint_descriptor *usb_endpoint_info::descr
-  \brief Pointer to the descriptor of the endpoint.
+  \brief a pointer to the descriptor of the endpoint
 */
 
 /*!
   \var usb_pipe usb_endpoint_info::handle
-  \brief Handle to use when using the stack to transfer data to and from this
-    endpoint.
+  \brief a handle to use when using the stack to transfer data to and from this
+    endpoint
 */
 
 ///// usb_interface_info /////
 
 /*!
   \struct usb_interface_info
-  \brief Container for interface descriptors and their Haiku USB stack
-    identifiers.
+  \brief acontainer for interface descriptors and their Haiku USB stack
+    identifiers
 */
 
 //! @{
 
 /*!
   \var usb_interface_descriptor *usb_interface_info::descr
-  \brief Pointer to the descriptor of the interface.
+  \brief a pointer to the descriptor of the interface
 */
 
 /*!
   \var usb_interface usb_interface_info::handle
-  \brief Handle to use when using the stack to manipulate this interface.
+  \brief a handle to use when using the stack to manipulate this interface
 */
 
 //! @}
@@ -197 +197 @@
 
 /*!
   \var size_t usb_interface_info::endpoint_count
-  \brief The number of endpoints in this interface.
+  \brief the number of endpoints in this interface
 */
 
 /*!
   \var usb_endpoint_info *usb_interface_info::endpoint
-  \brief An array of endpoints that are associated to this interface.
+  \brief an array of endpoints that are associated to this interface
 */
 
 //! @}
@@ -215 +215 @@
 
 /*!
   \var size_t usb_interface_info::generic_count
-  \brief The number of unparsed descriptors in this interface.
+  \brief the number of unparsed descriptors in this interface
 */
 
 /*!
   \var usb_descriptor **usb_interface_info::generic
-  \brief Unparsed descriptors in this interface.
+  \brief unparsed descriptors in this interface
 */
 
 //! @}
@@ -229 +229 @@
 
 /*!
   \struct usb_interface_list
-  \brief List of interfaces available to a configuration.
+  \brief the list of interfaces available to a configuration
 */
 
 /*!
   \var size_t usb_interface_list::alt_count
-  \brief Number of available interfaces.
+  \brief the number of available interfaces
 */
 
 /*!
   \var usb_interface_info *usb_interface_list::alt
-  \brief Array of available interfaces.
+  \brief the array of available interfaces
 */
 
 /*!
   \var usb_interface_info *usb_interface_list::active
-  \brief Pointer to active interface.
+  \brief the pointer to active interface
 */
 
 ///// usb_configuration_info /////
 
 /*!
   \struct usb_configuration_info
-  \brief Container for a specific configuration descriptor of a device.
+  \brief a container for a specific configuration descriptor of a device
 */
 
 /*!
   \var usb_configuration_descriptor *usb_configuration_info::descr
-  \brief The configuration descriptor.
+  \brief the configuration descriptor
 */
 
 /*!
   \var size_t usb_configuration_info::interface_count
-  \brief The number of interfaces in this configuration.
+  \brief the number of interfaces in this configuration
 */
 
 /*!
   \var usb_interface_list *usb_configuration_info::interface
-  \brief The list of interfaces available to this configuration.
+  \brief the list of interfaces available to this configuration
 */
 
 ///// usb_iso_packet_descriptor /////
 
 /*!
   \struct usb_iso_packet_descriptor
-  \brief The descriptor for data packets of isochronous transfers.
+  \brief the descriptor for data packets of isochronous transfers
 */
 
 /*!
   \var int16 usb_iso_packet_descriptor::req_len
-  \brief Length of the request.
+  \brief the length of the request
 */
 
 /*!
@@ -288 +288 @@
 
 /*!
   \var status_t usb_iso_packet_descriptor::status
-  \brief The status of the transfer.
+  \brief the status of the transfer
 */
   
 ///// usb_callback_func /////
 
 /*!
   \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength)
-  \brief Callback function for asynchronous transfers.
+  \brief callback function for asynchronous transfers
 
-  \param cookie The cookie you supplied when you queued the transfer.
-  \param status The status of the transfer. This is one of the following:
+  \param cookie the cookie you supplied when you queued the transfer
+  \param status This is the status of the transfer. It can be one of the following:
     <table>
       <tr>
-        <td><em>B_OK</em></td><td>Transfer succeeded.</td>
+        <td><em>B_OK</em></td><td>The transfer succeeded.</td>
       </tr>
       <tr>
-        <td><em>B_CANCELED</em></td><td>Transfer cancelled by the user via a 
-          usb_module_info::cancel_queued_transfers() call.</td>
+        <td><em>B_CANCELED</em></td><td>The transfer was cancelled by the user
+          via a usb_module_info::cancel_queued_transfers() call.</td>
       </tr>
       <tr>
         <td><em>B_DEV_MULTIPLE_ERRORS</em></td><td>More than one of the errors
-          below. Unfortunately, the stack cannot give you more information.</td>
+          below occurred. Unfortunately, the stack cannot give you more
+          information.</td>
       </tr>
       <tr>
         <td><em>B_DEV_STALLED</em></td><td>The endpoint is stalled. You can use
@@ -322 +323 @@
       </tr>
       <tr>
         <td><em>B_DEV_DATA_UNDERRUN</em></td><td>Outgoing transfer: more data
-          flowing out than the endpoint accepts.</td>
+          is flowing out than the endpoint accepts.</td>
       </tr>
       <tr>
         <td><em>B_DEV_CRC_ERROR</em></td><td>The internal data consistency
-          checks of the USB protocol failed. You are best to retry. If you keep
-          on getting this error, there might be something wrong with the
+          checks of the USB protocol failed. It is best to retry. If you keep
+          on getting this error there might be something wrong with the
           device.</td>
       </tr>
       <tr>
-        <td><em>B_DEV_UNEXPECTED_PID</em></td><td>Internal error. You should
-          retry your transfer.</td>
+        <td><em>B_DEV_UNEXPECTED_PID</em></td><td>There was an internal error.
+          You should retry your transfer.</td>
       </tr>
       <tr>
-        <td><em>B_DEV_FIFO_OVERRUN</em></td><td>Internal error. You should
-          retry your transfer.</td>
+        <td><em>B_DEV_FIFO_OVERRUN</em></td><td>There was an internal error.
+          You should retry your transfer.</td>
       </tr>
       <tr>
-         <td><em>B_DEV_FIFO_UNDERRUN</em></td><td>Internal error. You should
-          retry your transfer.</td>
+         <td><em>B_DEV_FIFO_UNDERRUN</em></td><td>There was an internal error.
+           You should retry your transfer.</td>
       </tr>
     </table>
-  \param data The provided buffer.
-  \param actualLength The amount of bytes read or written during the transfer.
+  \param data the provided buffer
+  \param actualLength the amount of bytes read or written during the transfer
 */
 
 ///// usb_module_info /////
 
 /*!
   \struct usb_module_info
-  \brief Interface for drivers to interact with Haiku's USB stack.
+  \brief interface for drivers to interact with Haiku's USB stack
 */
 
 /*!
   \var usb_module_info::binfo
-  \brief Instance of the bus_manager_info object.
+  \brief instance of the bus_manager_info object
 */
 
 /*!
@@ -364 +365 @@
   \brief Register your driver.
   
   To let the USB stack know that a driver is available to support devices, a
-  driver needs to register itself first. To let the stack know which devices
+  driver needs to register itself first. To let the stack know about devices
   it needs to notify the driver of, have a look at usb_support_descriptor.
   
   It is possible to supply a list of support constructors. You should allocate
-  an array of support constructors, and give the amount of constructors in the
+  an array of support constructors and give the amount of constructors in the
   array using the \a supportDescriptorCount parameter.
   
-  In case your driver supports all devices, or more likely, in case you want to
+  In case your driver supports all devices or, more likely, you want to
   monitor all devices plugged in and removed, it is safe to pass \c NULL to the
   \a supportDescriptors paramater and zero (0) to \a supportDescriptorCount.
   
-  \param driverName A unique name that identifies your driver. Avoid names like
+  \param driverName This is a unique name that identifies your driver. Avoid names like
     \c webcam or \c mouse, instead use vendor names and device types to avoid
     nameclashes. The install_notify() and uninstall_notify() functions use the
     driver name as an identifier.
-  \param supportDescriptors An array of the type usb_support_descriptor. Pass
+  \param supportDescriptors This is an array of the type usb_support_descriptor. Pass
     the amount of objects in the next parameter.
-  \param supportDescriptorCount The number of objects in the array supplied in
-    the previous parameter.
+  \param supportDescriptorCount the number of objects in the array supplied in
+    the previous parameter
   \param optionalRepublishDriverName Unused parameter. You should pass \c NULL.
   \retval B_OK The driver is registered. You can now call install_notify()
   \retval B_BAD_VALUE You passed \c NULL as \a driverName.
-  \retval B_ERROR General internal error in the USB stack. You may retry the
+  \retval B_ERROR A general internal error in the USB stack occured. You may retry the
     request in this case.
-  \retval B_NO_MEMORY Error allocating some internal objects. The system is
+  \retval B_NO_MEMORY An error allocating some internal objects occured. The system is
     out of memory.
 */
 
@@ -400 +401 @@
   are called whenever a device that matches your \link usb_support_descriptor
   support descriptor \endlink . 
   
-  As soon as the hooks are installed you'll receive callbacks for devices that
-  are already attached, so make sure your driver is initialized properly when
+  As soon as the hooks are installed, you'll receive callbacks for devices that
+  are already attached; so make sure your driver is initialized properly when
   calling this method. 
   
-  \param driverName The name you passed in register_driver(). 
-  \param hooks The hooks the stack should call in case the status of devices
-    that match your support descriptor changes.
+  \param driverName the name you passed in register_driver()
+  \param hooks the hooks the stack should call in case the status of devices
+    that match your support descriptor changes
   \retval B_OK Hooks are installed succesfully.
-  \retval B_NAME_NOT_FOUND Invalid \a driverName. 
+  \retval B_NAME_NOT_FOUND invalid \a driverName
   
   \see usb_notify_hooks for information on how your hooks should behave.
   \see uninstall_notify()
@@ -419 +420 @@
   \brief Uninstall notify hooks for your driver.
   
   If your driver needs to stop, you can uninstall the notifier hooks. This will
-  clear the stored hooks in the driver and you will not receive any
+  clear the stored hooks in the driver, and you will not receive any
   notifications when new devices are attached. This method will also call
   usb_notify_hooks::device_removed() for all the devices that you are using and
   all the stack's resources that are allocated to your driver are cleared.
   
-  \param driverName The name you passed in register_driver().
-  \retval B_OK Hooks are uninstalled.
-  \retval B_NAME_NOT_FOUND Invalid \a driverName.
+  \param driverName the name you passed in register_driver()
+  \retval B_OK hooks are uninstalled
+  \retval B_NAME_NOT_FOUND invalid \a driverName
 */
 
 /*!
   \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device)
   \brief Get the device descriptor.
   
-  \param device The id of the device you want to query. 
-  \return The standard usb_device_descriptor, or \c NULL in case of an error.
+  \param device the id of the device you want to query
+  \return the standard usb_device_descriptor or \c NULL in case of an error
 */
 
 /*!
   \fn const usb_configuration_info  *(*usb_module_info::get_nth_configuration)(usb_device device, uint index)
   \brief Get a configuration descriptor by index.
   
-  \param device The id of the device you want to query.
-  \param index The (zero based) offset of the list of configurations.
-  \return The usb_configuration_info with the standard usb configuration 
-    descriptor, or \c NULL if the \a id is invalid or the \a index is out of
-    bounds.
+  \param device the id of the device you want to query
+  \param index the (zero based) offset of the list of configurations
+  \return This will normally return the usb_configuration_info with the
+    standard usb configuration descriptor.  \c NULL will be returned if the
+    \a id is invalid or the \a index is out of bounds.
 */
 
 /*!
   \fn const usb_configuration_info  *(*usb_module_info::get_configuration)(usb_device device)
   \brief Get the current configuration.
   
-  \param id The id of the device you want to query.
-  \retval The usb_configuration_info with the standard usb configuration
-    descriptor, or \c NULL if the \a id is invalid.
+  \param id the id of the device you want to query
+  \retval This will return usb_configuration_info with the standard usb
+    configuration descriptor, or it will return\c NULL if the \a id is invalid.
 */
 
 /*!
@@ -465 +466 @@
   \a configuration points to the current configuration, the request will be
   ignored and \c B_OK will be returned. 
   
-  \param device The id of the device you want to query.
-  \param configuration The pointer to the new configuration you want to set.
+  \param device the id of the device you want to query
+  \param configuration the pointer to the new configuration you want to set
   \retval B_OK The new configuration is set succesfully.
   \retval B_DEV_INVALID_PIPE The \a device parameter is invalid.
   \retval B_BAD_VALUE The configuration does not exist.
@@ -478 +479 @@
 
 /*!
   \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface)
-  \brief Set an alternative interface. Not implemented.
+  \brief Set an alternative interface. This is not implemented.
   
   This method currently always returns \c B_ERROR.
 */
 
 /*!
   \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector)
-  \brief Convenience function for standard control pipe set feature requests.  
+  \brief convenience function for standard control pipe set feature requests
 
   Both the set_feature() and clear_feature() requests work on all the Stack's
   objects: devices, interfaces and pipes.
   
-  \param handle The object you want to query.
-  \param selector The value you want to pass in the feature request. 
-  \return \c B_OK in case the request succeeded and the device responded
-    positively, or an error code in case it failed.
+  \param handle the object you want to query
+  \param selector the value you want to pass in the feature request
+  \return This returns \c B_OK in case the request succeeded and the device
+    responded positively, or it returns an error code in case it failed.
 */
 
 /*!
   \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector)
-  \brief Convenience function for standard control pipe clear feature requests.
+  \brief convenience function for standard control pipe clear feature requests
   
   \see set_feature() to see how this method works.
 */
@@ -507 +508 @@
   \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status)
   \brief Convenience function for standard usb status requests. 
   
-  \param[in] handle The object you want to query.
-  \param[out] status A variable in which the device can store it's status.
-  \return \c B_OK in case the request succeeded and the device responded
-    positively, or an error code in case it failed.
+  \param[in] handle the object you want to query
+  \param[out] status a variable in which the device can store it's status
+  \return \c B_OK is returned in case the request succeeded and the device
+    responded positively, or an error code is returned in case it failed.
 */
   
 /*!
   \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength,  size_t *actualLength)
-  \brief Convenience function to get a descriptor from a device.
+  \brief convenience function to get a descriptor from a device
   
-  \param[in] device The device you want to query.
-  \param[in] descriptorType The type of descriptor you are requesting.
+  \param[in] device the device you want to query
+  \param[in] descriptorType the type of descriptor you are requesting
   \param[in] index In case there are multiple descriptors of this type, you
     select which one you want.
-  \param[in] languageID The language you want the descriptor in (if applicable,
-    like with string_descriptors). 
-  \param[out] data The buffer in which the descriptor can be written.
-  \param[in] dataLength The size of the buffer (in bytes).
-  \param[out] actualLength A pointer to a variable in which the actual number
-    of bytes written can be stored.
+  \param[in] languageID the language you want the descriptor in (if applicable,
+    as with string_descriptors)
+  \param[out] data the buffer in which the descriptor can be written
+  \param[in] dataLength the size of the buffer (in bytes)
+  \param[out] actualLength a pointer to a variable in which the actual number
+    of bytes written can be stored
   \retval B_OK The request succeeded, and the descriptor is written.
-  \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
-  \retval "other errors" Request failed.
+  \retval B_DEV_INVALID_PIPE invalid \a device parameter
+  \retval "other errors" The Request failed.
 */
   
 /*!
@@ -540 +541 @@
   
   Most of the standard values of a request are defined in USB_spec.h.
   
-  \param[in] device The device you want to query.
-  \param[in] requestType The request type.
-  \param[in] request The request you want to perform.
-  \param[in] value The value of the request.
-  \param[in] index The index for the request.
-  \param[in] length  The size of the buffer pointed by \a data
-  \param[out] data The buffer where to put the result in. 
-  \param[out] actualLength The actual numbers of bytes written.
+  \param[in] device the device you want to query
+  \param[in] requestType the request type
+  \param[in] request the request you want to perform
+  \param[in] value the value of the request
+  \param[in] index the index for the request
+  \param[in] length the size of the buffer pointed by \a data
+  \param[out] data the buffer where to put the result in
+  \param[out] actualLength the actual numbers of bytes written
   
-  \retval B_OK The request succeeded.
-  \retval B_DEV_INVALID_PIPE Invalid \a device parameter.
-  \retval "other errors" Request failed.
+  \retval B_OK the request succeeded
+  \retval B_DEV_INVALID_PIPE invalid \a device parameter
+  \retval "other errors" The request failed.
 */
 
 /*!
   \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie)
   \brief Asynchronously queue an interrupt transfer.
   
-  \param pipe The id of the pipe you want to query. 
-  \param data The data buffer you want to pass.
-  \param dataLength The size of the data buffer.
-  \param callback The callback function the stack should call after finishing.
-  \param callbackCookie A cookie that will be supplied to your callback
-    function when the transfer is finished.
+  \param pipe the id of the pipe you want to query
+  \param data the data buffer you want to pass
+  \param dataLength the size of the data buffer
+  \param callback the callback function the stack should call after finishing
+  \param callbackCookie a cookie that will be supplied to your callback
+    function when the transfer is finished
   
-  \return Whether or not the queueing of the transfer went well. The return
-   value won't tell you if the transfer actually succeeded.
+  \return This will return a value indicating whether or not the queueing of
+    the transfer went well. The return value won't tell you if the transfer
+    actually succeeded.
   \retval B_OK The interrupt transfer is queued.
-  \retval B_NO_MEMORY Error allocating objects.
+  \retval B_NO_MEMORY error allocating objects
   \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe.
 */
 
@@ -587 +589 @@
   This method behaves like the queue_interrupt() method, except that it queues
   bulk transfers and that it is based on an (array of) io vectors.
   
-  \param vector One or more io vectors. IO vectors are standard POSIX entities.
-  \param vectorCount The number of elements in the \a vector array.
+  \param vector This contains one or more io vectors. IO vectors are standard
+    POSIX entities.
+  \param vectorCount the number of elements in the \a vector array
 */
 
 /*!
   \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie)
-  \brief Asynchronously queue a isochronous transfer. Not implemented.
+  \brief Asynchronously queue a isochronous transfer. This is not implemented.
   
-  Not implemented in the current Haiku USB Stack.
+  This is not implemented in the current Haiku USB Stack.
 */
 
 /*!
@@ -606 +609 @@
   asynchronously. This means that the method will return as soon as the
   transfer is queued. 
   
-  \param callback The callback function for when the transfer is done.
-  \param callbackCookie The cookie that the stack should pass to your callback
-    function.
-    \return Whether or not the queueing of the transfer went well. The return
-   value won't tell you if the transfer actually succeeded.
-  \retval B_OK The control transfer is queued.
-  \retval B_NO_MEMORY Error allocating objects.
-  \retval B_DEV_INVALID_PIPE The \a device argument is invalid.
+  \param callback the callback function for when the transfer is done
+  \param callbackCookie the cookie that the stack should pass to your callback
+    functiont
+  \return This will return a value indicating whether or not the queueing of
+    the transfer went well. The return value won't tell you if the transfer
+    actually succeeded.
+  \retval B_OK the control transfer is queued
+  \retval B_NO_MEMORY error allocating objects
+  \retval B_DEV_INVALID_PIPE the \a device argument is invalid
 */
 
 /*!
@@ -621 +625 @@
   \brief Set some pipe features.
   
   The USB standard specifies some properties that should be able to be set on
-   isochronous pipes. If your driver requires the properties to be changed, you
-   should use this method. 
+  isochronous pipes. If your driver requires the properties to be changed, you
+  should use this method. 
   
-  \param pipe The id of the isochronous pipe you want to alter.
-  \param maxNumQueuedPackets The maximum number of queued packets allowed on
-    this pipe.
-  \param maxBufferDurationMS The maximum time in ms that the buffers are valid.
-  \param sampleSize The size of the samples through this pipe.
-  \retval B_OK Pipe policy changed.
+  \param pipe the id of the isochronous pipe you want to alter
+  \param maxNumQueuedPackets the maximum number of queued packets allowed on
+    this pipe
+  \param maxBufferDurationMS the maximum time in ms that the buffers are valid
+  \param sampleSize the size of the samples through this pipe
+  \retval B_OK The pipe policy changed.
   \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an
     isochronous pipe.
 */
@@ -646 +650 @@
     performed. Make sure you don't delete any buffers that could still be used
     by these transfers.
   
-  \param pipe The id of the pipe to clear.
+  \param pipe the id of the pipe to clear
   
   \retval B_OK All the pending transfers on this pipe are deleted.
   \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe.
@@ -657 +661 @@
   \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize)
   \brief Low level commands to the USB stack.
   
-  This method is used to give lowlevel commands to the Stack. There are
+  This method is used to give low level commands to the Stack. There are
   currently no uses documented.
 */
 
@@ -665 +669 @@
 
 /*!
   \def B_USB_MODULE_NAME
-  \brief The identifier string for the USB Stack interface module.
+  \brief the identifier string for the USB Stack interface module
 */