Better documentation for the Endpoint_ConfigureEndpoint() and Pipe_ConfigurePipe...

diff --git a/LUFA/Drivers/USB/LowLevel/Device.h b/LUFA/Drivers/USB/LowLevel/Device.h
index fdf4ee9..17984c7 100644 (file)
--- a/LUFA/Drivers/USB/LowLevel/Device.h
+++ b/LUFA/Drivers/USB/LowLevel/Device.h
@@ -100,7 +100,7 @@
                         *        issued if the host is currently allowing remote wakeup events from the device (i.e.,
                         *        the \ref USB_RemoteWakeupEnabled flag is set). When the NO_DEVICE_REMOTE_WAKEUP compile
                         *        time option is used, this macro is unavailable.
                         *        issued if the host is currently allowing remote wakeup events from the device (i.e.,
                         *        the \ref USB_RemoteWakeupEnabled flag is set). When the NO_DEVICE_REMOTE_WAKEUP compile
                         *        time option is used, this macro is unavailable.

-                        *        \n
+                        *        \n\n

                         *
                         *  \note The USB clock must be running for this function to operate. If the stack is initialized with
                         *        the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running
                         *
                         *  \note The USB clock must be running for this function to operate. If the stack is initialized with
                         *        the \ref USB_OPT_MANUAL_PLL option enabled, the user must ensure that the PLL is running

diff --git a/LUFA/Drivers/USB/LowLevel/Endpoint.h b/LUFA/Drivers/USB/LowLevel/Endpoint.h
index 0b0a472..2a8344b 100644 (file)
--- a/LUFA/Drivers/USB/LowLevel/Endpoint.h
+++ b/LUFA/Drivers/USB/LowLevel/Endpoint.h
@@ -245,25 +245,38 @@
 
                /* Inline Functions: */                 
                        /** Configures the specified endpoint number with the given endpoint type, direction, bank size
 
                /* Inline Functions: */                 
                        /** Configures the specified endpoint number with the given endpoint type, direction, bank size

-                        *  and banking mode. Endpoints should be allocated in ascending order by their address in the
-                        *  device (i.e. endpoint 1 should be configured before endpoint 2 and so on) to prevent fragmentation
-                        *  of the USB FIFO memory.
+                        *  and banking mode. Once configured, the endpoint may be read from or written to, depending
+                        *  on its direction.

                         *
                         *

-                        *  The endpoint type may be one of the EP_TYPE_* macros listed in LowLevel.h and the direction
-                        *  may be either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
+                        *  \param[in] Number     Endpoint number to configure. This must be more than 0 and less than
+                        *                        \ref ENDPOINT_TOTAL_ENDPOINTS.

                         *
                         *

-                        *  The bank size must indicate the maximum packet size that the endpoint can handle. Different
-                        *  endpoint numbers can handle different maximum packet sizes - refer to the chosen USB AVR's
-                        *  datasheet to determine the maximum bank size for each endpoint.
+                        *  \param[in] Type       Type of endpoint to configure, a EP_TYPE_* mask. Not all endpoint types
+                        *                        are available on Low Speed USB devices - refer to the USB 2.0 specification.

                         *
                         *

-                        *  The banking mode may be either \ref ENDPOINT_BANK_SINGLE or \ref ENDPOINT_BANK_DOUBLE.
+                        *  \param[in] Direction  Endpoint data direction, either \ref ENDPOINT_DIR_OUT or \ref ENDPOINT_DIR_IN.
+                        *                        All endpoints (except Control type) are unidirectional - data may only be read
+                        *                        from or written to the endpoint bank based on its direction, not both.
+                        *
+                        *  \param[in] Size       Size of the endpoint's bank, where packets are stored before they are transmitted
+                        *                        to the USB host, or after they have been received from the USB host (depending on
+                        *                        the endpoint's data direction). The bank size must indicate the maximum packet size
+                        *                        that the endpoint can handle.
+                        *
+                        *  \param[in] Banks      Number of banks to use for the endpoint being configured, an ENDPOINT_BANK_* mask.
+                        *                        More banks uses more USB DPRAM, but offers better performance. Isochronous type
+                        *                        endpoints <b>must</b> have at least two banks.
+                        *
+                        *  \note Certain models of USB AVR's endpoints may have different maximum packet sizes based on the endpoint's
+                        *        index - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each endpoint.
+                        *        \n\n

                         *
                         *  \note The default control endpoint should not be manually configured by the user application, as 
                         *        it is automatically configured by the library internally.
                         *        \n\n
                         *
                         *
                         *  \note The default control endpoint should not be manually configured by the user application, as 
                         *        it is automatically configured by the library internally.
                         *        \n\n
                         *

-                        *  \note This routine will select the specified endpoint, and the endpoint will remain selected
-                        *        once the routine completes regardless of if the endpoint configuration succeeds.
+                        *  \note This routine will automatically select the specified endpoint upon success. Upon failure, the endpoint
+                        *        which failed to reconfigure correctly will be selected.

                         *
                         *  \return Boolean true if the configuration succeeded, false otherwise.
                         */
                         *
                         *  \return Boolean true if the configuration succeeded, false otherwise.
                         */

diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h
index d288ae2..835ca8b 100644 (file)
--- a/LUFA/Drivers/USB/LowLevel/Pipe.h
+++ b/LUFA/Drivers/USB/LowLevel/Pipe.h
@@ -811,18 +811,7 @@
 
                /* Function Prototypes: */
                        /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the
 
                /* Function Prototypes: */
                        /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the

-                        *  attached device, bank size and banking mode. Pipes should be allocated in ascending order by their
-                        *  address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation
-                        *  of the USB FIFO memory.
-                        *
-                        *  The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the
-                        *  PIPE_TOKEN_* masks.
-                        *
-                        *  The bank size must indicate the maximum packet size that the pipe can handle. Different pipe
-                        *  numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to
-                        *  determine the maximum bank size for each pipe.
-                        *
-                        *  The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE.
+                        *  attached device, bank size and banking mode.

                         *
                         *  A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze()
                         *  before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or
                         *
                         *  A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze()
                         *  before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or


@@ -830,14 +819,38 @@
                         *  numbers of IN requests without automatic freezing - this can be overridden by a call to
                         *  \ref Pipe_SetFiniteINRequests().
                         *
                         *  numbers of IN requests without automatic freezing - this can be overridden by a call to
                         *  \ref Pipe_SetFiniteINRequests().
                         *

-                        *  \note The default control pipe should not be manually configured by the user application, as it 
-                        *        is automatically configured by the library internally.
+                        *  \param[in] Number          Pipe number to configure. This must be more than 0 and less than \ref PIPE_TOTAL_PIPES.
+                        *
+                        *  \param[in] Type            Type of pipe to configure, a EP_TYPE_* mask. Not all pipe types are available on Low
+                        *                             Speed USB devices - refer to the USB 2.0 specification.
+                        *
+                        *  \param[in] Token           Pipe data token, either \ref PIPE_TOKEN_SETUP, \ref PIPE_TOKEN_OUT or \ref PIPE_TOKEN_IN.
+                        *                             All pipes (except Control type) are unidirectional - data may only be read from or 
+                        *                             written to the pipe bank based on its direction, not both.
+                        *
+                        *  \param[in] EndpointNumber  Endpoint index within the attached device that the pipe should interface to.
+                        *
+                        *  \param[in] Size            Size of the pipe's bank, where packets are stored before they are transmitted to
+                        *                             the USB device, or after they have been received from the USB device (depending on 
+                        *                             the pipe's data direction). The bank size must indicate the maximum packet size that 
+                        *                             the pipe can handle.
+                        *
+                        *  \param[in] Banks           Number of banks to use for the pipe being configured, a PIPE_BANK_* mask. More banks
+                        *                             uses more USB DPRAM, but offers better performance. Isochronous type pipes <b>must</b>
+                        *                             have at least two banks.
+                        *
+                        *  \note Certain models of USB AVR's pipes may have different maximum packet sizes based on the pipe's
+                        *        index - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each pipe.
+                        *        \n\n
+                        *
+                        *  \note The default control pipe should not be manually configured by the user application, as it is
+                        *        automatically configured by the library internally.

                         *        \n\n
                         *
                         *        \n\n
                         *

-                        *  \note This routine will select the specified pipe, and the pipe will remain selected once the
-                        *        routine completes regardless of if the pipe configuration succeeds.
+                        *  \note This routine will automatically select the specified pipe upon success. Upon failure, the pipe which
+                        *        failed to reconfigure correctly will be selected.

                         *
                         *

-                        *  \return Boolean true if the configuration is successful, false otherwise.
+                        *  \return Boolean true if the configuration succeeded, false otherwise.

                         */
                        bool Pipe_ConfigurePipe(const uint8_t  Number,
                                                const uint8_t Type,
                         */
                        bool Pipe_ConfigurePipe(const uint8_t  Number,
                                                const uint8_t Type,