Removed SerialStream module, rolled functionality into the base USART Serial peripheral driver instead through the new Serial_CreateStream() and Serial_CreateBlockingStream() methods.

Renamed the Serial byte send/receive functions to remain consistent with the CDC driver's byte functions.

Altered the serial byte receive function to make it non-blocking.

4 files changed, 83 insertions, 73 deletions

diff --git a/LUFA/Drivers/USB/Class/Common/HID.h b/LUFA/Drivers/USB/Class/Common/HID.h
index d28417ed5..485b9dbb0 100644
--- a/LUFA/Drivers/USB/Class/Common/HID.h
+++ b/LUFA/Drivers/USB/Class/Common/HID.h
@@ -343,11 +343,11 @@
 		 *  Where \c uintA_t is a type large enough to hold one bit per button, and \c intB_t is a type large enough to hold the
 		 *  ranges of the signed \c MinAxisVal and \c MaxAxisVal values.
 		 *
-		 *  \param[in] MinAxisVal      Minimum X/Y logical axis value
-		 *  \param[in] MaxAxisVal      Maximum X/Y logical axis value
-		 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations
-		 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations
-		 *  \param[in] Buttons         Total number of buttons in the device
+		 *  \param[in] MinAxisVal      Minimum X/Y logical axis value.
+		 *  \param[in] MaxAxisVal      Maximum X/Y logical axis value.
+		 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations.
+		 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations.
+		 *  \param[in] Buttons         Total number of buttons in the device.
 		 */
 		#define HID_DESCRIPTOR_JOYSTICK(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons) \
 			HID_RI_USAGE_PAGE(8, 0x01),                     \
@@ -393,7 +393,7 @@
 		 *  \endcode
 		 *
 		 *  \param[in] MaxKeys  Number of simultaneous keys that can be reported at the one time (a value between 1 and
-		 *                      (ENDPOINT_SIZE - 2) )
+		 *                      (ENDPOINT_SIZE - 2) ).
 		 */
 		#define HID_DESCRIPTOR_KEYBOARD(MaxKeys)            \
 			HID_RI_USAGE_PAGE(8, 0x01),                     \
@@ -446,12 +446,12 @@
 		 *  Where \c intA_t is a type large enough to hold one bit per button, and \c intB_t is a type large enough to hold the
 		 *  ranges of the signed \c MinAxisVal and \c MaxAxisVal values.
 		 *
-		 *  \param[in] MinAxisVal      Minimum X/Y logical axis value
-		 *  \param[in] MaxAxisVal      Maximum X/Y logical axis value
-		 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations
-		 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations
-		 *  \param[in] Buttons         Total number of buttons in the device
-		 *  \param[in] AbsoluteCoords  Boolean true to use absolute X/Y coordinates (e.g. touchscreen)
+		 *  \param[in] MinAxisVal      Minimum X/Y logical axis value.
+		 *  \param[in] MaxAxisVal      Maximum X/Y logical axis value.
+		 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations.
+		 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations.
+		 *  \param[in] Buttons         Total number of buttons in the device.
+		 *  \param[in] AbsoluteCoords  Boolean true to use absolute X/Y coordinates (e.g. touchscreen).
 		 */
 		#define HID_DESCRIPTOR_MOUSE(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons, AbsoluteCoords) \
 			HID_RI_USAGE_PAGE(8, 0x01),                     \
@@ -488,11 +488,11 @@
 		 *  used for transporting abitrary data between the USB host and device via HID reports. The resulting report should be
 		 *  a uint8_t byte array of the specified length in both Device to Host (IN) and Host to Device (OUT) directions.
 		 *
-		 *  \param[in] VendorPageNum    Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF
-		 *  \param[in] CollectionUsage  Vendor Usage for the encompasing report IN and OUT collection, ranging from 0x00 to 0xFF
-		 *  \param[in] DataINUsage      Vendor Usage for the IN report data, ranging from 0x00 to 0xFF
-		 *  \param[in] DataOUTUsage     Vendor Usage for the OUT report data, ranging from 0x00 to 0xFF   
-		 *  \param[in] NumBytes         Length of the data IN and OUT reports
+		 *  \param[in] VendorPageNum    Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF.
+		 *  \param[in] CollectionUsage  Vendor Usage for the encompasing report IN and OUT collection, ranging from 0x00 to 0xFF.
+		 *  \param[in] DataINUsage      Vendor Usage for the IN report data, ranging from 0x00 to 0xFF.
+		 *  \param[in] DataOUTUsage     Vendor Usage for the OUT report data, ranging from 0x00 to 0xFF.   
+		 *  \param[in] NumBytes         Length of the data IN and OUT reports.
 		 */
 		#define HID_DESCRIPTOR_VENDOR(VendorPageNum, CollectionUsage, DataINUsage, DataOUTUsage, NumBytes) \
 			HID_RI_USAGE_PAGE(16, (0xFF00 | VendorPageNum)), \
diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.h b/LUFA/Drivers/USB/Class/Common/HIDParser.h
index 8347f1dcf..c1689fad8 100644
--- a/LUFA/Drivers/USB/Class/Common/HIDParser.h
+++ b/LUFA/Drivers/USB/Class/Common/HIDParser.h
@@ -44,13 +44,20 @@
  *    - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
  *
  *  \section Sec_ModDescription Module Description
- *  Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
+ *  Human Interface Device (HID) class report descriptor parser. This module implements a parser than is
+ *  capable of processing a complete HID report descriptor, and outputting a flat structure containing the
+ *  contents of the report in an a more friendly format. The parsed data may then be further processed and used
+ *  within an application to process sent and received HID reports to and from an attached HID device.
  *
- *  The processed HID report is presented back to the user application as a flat structure containing each report
- *  item's IN, OUT and FEATURE items along with each item's attributes.
+ *  A HID report descriptor consists of a set of HID report items, which describe the function and layout
+ *  of data exchanged between a HID device and a host, including both the physical encoding of each item
+ *  (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" -
+ *  as well as other information about each item such as the usages, data range, physical location and other
+ *  characterstics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it
+ *  is not forced to comply with a given report layout or featureset.
  *
- *  This library portion also allows for easy setting and retrieval of data from a HID report, including devices
- *  with multiple reports on the one HID interface.
+ *  This module also contains routines for the processing of data in an actual HID report, using the parsed report
+ *  descritor data as a guide for the encoding.
  *
  *  @{
  */
@@ -159,8 +166,8 @@
 			 */
 			typedef struct
 			{
-				uint32_t                     Minimum; /**< Minimum value for the attribute. */
-				uint32_t                     Maximum; /**< Maximum value for the attribute. */
+				uint32_t Minimum; /**< Minimum value for the attribute. */
+				uint32_t Maximum; /**< Maximum value for the attribute. */
 			} HID_MinMax_t;
 
 			/** \brief HID Parser Report Item Unit Structure.
@@ -169,8 +176,8 @@
 			 */
 			typedef struct
 			{
-				uint32_t                     Type;     /**< Unit type (refer to HID specifications for details). */
-				uint8_t                      Exponent; /**< Unit exponent (refer to HID specifications for details). */
+				uint32_t Type;     /**< Unit type (refer to HID specifications for details). */
+				uint8_t  Exponent; /**< Unit exponent (refer to HID specifications for details). */
 			} HID_Unit_t;
 
 			/** \brief HID Parser Report Item Usage Structure.
@@ -179,8 +186,8 @@
 			 */
 			typedef struct
 			{
-				uint16_t                     Page;   /**< Usage page of the report item. */
-				uint16_t                     Usage;  /**< Usage of the report item. */
+				uint16_t Page;  /**< Usage page of the report item. */
+				uint16_t Usage; /**< Usage of the report item. */
 			} HID_Usage_t;
 
 			/** \brief HID Parser Report Item Collection Path Structure.
@@ -188,11 +195,11 @@
 			 *  Type define for a COLLECTION object. Contains the collection attributes and a reference to the
 			 *  parent collection if any.
 			 */
-			typedef struct CollectionPath
+			typedef struct HID_CollectionPath
 			{
-				uint8_t                      Type;   /**< Collection type (e.g. "Generic Desktop"). */
-				HID_Usage_t                  Usage;  /**< Collection usage. */
-				struct CollectionPath*       Parent; /**< Reference to parent collection, or \c NULL if root collection. */
+				uint8_t                    Type;   /**< Collection type (e.g. "Generic Desktop"). */
+				HID_Usage_t                Usage;  /**< Collection usage. */
+				struct HID_CollectionPath* Parent; /**< Reference to parent collection, or \c NULL if root collection. */
 			} HID_CollectionPath_t;
 
 			/** \brief HID Parser Report Item Attributes Structure.
@@ -201,12 +208,12 @@
 			 */
 			typedef struct
 			{
-				uint8_t                      BitSize;  /**< Size in bits of the report item's data. */
+				uint8_t      BitSize;  /**< Size in bits of the report item's data. */
 
-				HID_Usage_t                  Usage;    /**< Usage of the report item. */
-				HID_Unit_t                   Unit;     /**< Unit type and exponent of the report item. */
-				HID_MinMax_t                 Logical;  /**< Logical minimum and maximum of the report item. */
-				HID_MinMax_t                 Physical; /**< Physical minimum and maximum of the report item. */
+				HID_Usage_t  Usage;    /**< Usage of the report item. */
+				HID_Unit_t   Unit;     /**< Unit type and exponent of the report item. */
+				HID_MinMax_t Logical;  /**< Logical minimum and maximum of the report item. */
+				HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
 			} HID_ReportItem_Attributes_t;
 
 			/** \brief HID Parser Report Item Details Structure.
@@ -215,18 +222,18 @@
 			 */
 			typedef struct
 			{
-				uint16_t                     BitOffset;      /**< Bit offset in the IN, OUT or FEATURE report of the item. */
-				uint8_t                      ItemType;       /**< Report item type, a value in \ref HID_ReportItemTypes_t. */
-				uint16_t                     ItemFlags;      /**< Item data flags, a mask of HID_IOF_* constants. */
-				uint8_t                      ReportID;       /**< Report ID this item belongs to, or 0x00 if device has only one report */
-				HID_CollectionPath_t*        CollectionPath; /**< Collection path of the item. */
-
-				HID_ReportItem_Attributes_t  Attributes;     /**< Report item attributes. */
-
-				uint32_t                     Value;          /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing
-				                                              *   a retrieved value so that it is aligned to a specific type.
-				                                              */
-				uint32_t                     PreviousValue;  /**< Previous value of the report item. */
+				uint16_t                    BitOffset;      /**< Bit offset in the IN, OUT or FEATURE report of the item. */
+				uint8_t                     ItemType;       /**< Report item type, a value in \ref HID_ReportItemTypes_t. */
+				uint16_t                    ItemFlags;      /**< Item data flags, a mask of HID_IOF_* constants. */
+				uint8_t                     ReportID;       /**< Report ID this item belongs to, or 0x00 if device has only one report */
+				HID_CollectionPath_t*       CollectionPath; /**< Collection path of the item. */
+
+				HID_ReportItem_Attributes_t Attributes;     /**< Report item attributes. */
+
+				uint32_t                    Value;          /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing
+				                                             *   a retrieved value so that it is aligned to a specific type.
+				                                             */
+				uint32_t                    PreviousValue;  /**< Previous value of the report item. */
 			} HID_ReportItem_t;
 
 			/** \brief HID Parser Report Size Structure.
@@ -235,10 +242,10 @@
 			 */
 			typedef struct
 			{
-				uint8_t                      ReportID; /**< Report ID of the report within the HID interface. */
-				uint16_t                     ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID,
-				                                                 *   indexed by the \ref HID_ReportItemTypes_t enum.
-																 */
+				uint8_t  ReportID; /**< Report ID of the report within the HID interface. */
+				uint16_t ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID,
+				                             *   indexed by the \ref HID_ReportItemTypes_t enum.
+				                             */
 			} HID_ReportSizeInfo_t;
 
 			/** \brief HID Parser State Structure.
@@ -247,21 +254,19 @@
 			 */
 			typedef struct
 			{
-				uint8_t                      TotalReportItems; /**< Total number of report items stored in the
-				                                                *   \c ReportItems array.
-				                                                */
-				HID_ReportItem_t             ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including
-			                                                                    *   all IN, OUT and FEATURE items.
-				                                                                */
-				HID_CollectionPath_t         CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
-				                                                                    *   by the report items.
-				                                                                    */
-				uint8_t                      TotalDeviceReports; /**< Number of reports within the HID interface */
-				HID_ReportSizeInfo_t         ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
-				uint16_t                     LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
-				bool                         UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
-				                                              *   element in its HID report descriptor.
-				                                              */
+				uint8_t              TotalReportItems; /**< Total number of report items stored in the \c ReportItems array. */
+				HID_ReportItem_t     ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including all IN, OUT
+			                                                            *   and FEATURE items.
+				                                                        */
+				HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
+				                                                            *   by the report items.
+				                                                            */
+				uint8_t              TotalDeviceReports; /**< Number of reports within the HID interface */
+				HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
+				uint16_t             LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
+				bool                 UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
+				                                      *   element in its HID report descriptor.
+				                                      */
 			} HID_ReportInfo_t;
 
 		/* Function Prototypes: */
diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h
index 62ee0433f..85ab16396 100644
--- a/LUFA/Drivers/USB/Class/Device/CDC.h
+++ b/LUFA/Drivers/USB/Class/Device/CDC.h
@@ -280,12 +280,12 @@
 			void CDC_Device_SendControlLineStateChange(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
 			/** Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular
-			 *  functions in the avr-libc <stdio.h> library that accept a FILE stream as a destination (e.g. fprintf). The created
+			 *  functions in the avr-libc <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created
 			 *  stream is bidirectional and can be used for both input and output functions.
 			 *
 			 *  Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single
 			 *  fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may
-			 *  be used when the read data is processed byte-per-bye (via getc()) or when the user application will implement its own
+			 *  be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
 			 *  line buffering.
 			 *
 			 *  \note The created stream can be given as stdout if desired to direct the standard output from all <stdio.h> functions
@@ -297,7 +297,7 @@
 			void CDC_Device_CreateStream(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo,
 			                             FILE* const Stream) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
 
-			/** Identical to CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates
+			/** Identical to \ref CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates
 			 *  the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications.
 			 *
 			 *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state.
diff --git a/LUFA/Drivers/USB/Class/Host/CDC.h b/LUFA/Drivers/USB/Class/Host/CDC.h
index 9033cbfb9..3b84bb2d7 100644
--- a/LUFA/Drivers/USB/Class/Host/CDC.h
+++ b/LUFA/Drivers/USB/Class/Host/CDC.h
@@ -270,9 +270,14 @@
 			uint8_t CDC_Host_Flush(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
 			/** Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular
-			 *  functions in the avr-libc \c <stdio.h> library that accept a FILE stream as a destination (e.g. fprintf). The created
+			 *  functions in the avr-libc \c <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created
 			 *  stream is bidirectional and can be used for both input and output functions.
 			 *
+			 *  Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single
+			 *  fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may
+			 *  be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
+			 *  line buffering.
+			 *
 			 *  \note The created stream can be given as stdout if desired to direct the standard output from all \c <stdio.h> functions
 			 *        to the given CDC interface.
 			 *
@@ -282,7 +287,7 @@
 			void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
 			                           FILE* const Stream);
 
-			/** Identical to CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates
+			/** Identical to \ref CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates
 			 *  the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications.
 			 *
 			 *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state.