Deleted StdDescriptors.c, renamed USB_GetDescriptor() to CALLBACK_USB_GetDescriptor...

[pub/USBasp.git] / LUFA / Drivers / USB / Class / HIDParser.h

diff --git a/LUFA/Drivers/USB/Class/HIDParser.h b/LUFA/Drivers/USB/Class/HIDParser.h
index 314d080..49e57c2 100644 (file)
--- a/LUFA/Drivers/USB/Class/HIDParser.h
+++ b/LUFA/Drivers/USB/Class/HIDParser.h
@@ -33,7 +33,14 @@
  *  USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy\r
  *  parsing of the complex HID report descriptor, which describes the data that the device transmits to the host.\r
  *\r
  *  USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy\r
  *  parsing of the complex HID report descriptor, which describes the data that the device transmits to the host.\r
  *\r

- *  The processed report is presented back to the user application as a flat structure containing each report\r
+ */\r
+ \r
+/** \ingroup Group_USB\r
+ *  @defgroup Group_HIDParser HID Report Parser\r
+ *\r
+ *  Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.\r
+ *\r
+ *  The processed HID report is presented back to the user application as a flat structure containing each report\r

  *  item's IN, OUT and FEATURE (if desired) items along with each item's attributes.\r
  *\r
  *  This library portion also allows for easy setting and retrieval of data from a HID report, including devices\r
  *  item's IN, OUT and FEATURE (if desired) items along with each item's attributes.\r
  *\r
  *  This library portion also allows for easy setting and retrieval of data from a HID report, including devices\r


@@ -43,6 +50,8 @@
  *  to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or\r
  *  HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D\r
  *  switch.\r
  *  to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or\r
  *  HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D\r
  *  switch.\r

+ *\r
+ *  @{\r

  */\r
 \r
 #ifndef __HIDPARSER_H__\r
  */\r
 \r
 #ifndef __HIDPARSER_H__\r


@@ -105,7 +114,7 @@
 \r
        /* Public Interface - May be used in end-application: */\r
                /* Enums: */\r
 \r
        /* Public Interface - May be used in end-application: */\r
                /* Enums: */\r

-                       /** Enum for indicating what type of report item an entry in a HID_ReportInfo_t ReportItem array is */\r
+                       /** Enum for indicating what type of report item an entry in a \ref HID_ReportInfo_t ReportItem array is */\r

                        enum HID_ReportItemTypes_t\r
                        {\r
                                REPORT_ITEM_TYPE_In                   = 0, /**< Indicates that the item is an IN report type. */\r
                        enum HID_ReportItemTypes_t\r
                        {\r
                                REPORT_ITEM_TYPE_In                   = 0, /**< Indicates that the item is an IN report type. */\r


@@ -113,16 +122,16 @@
                                REPORT_ITEM_TYPE_Feature              = 2, /**< Indicates that the item is a FEATURE report type. */\r
                        };\r
                        \r
                                REPORT_ITEM_TYPE_Feature              = 2, /**< Indicates that the item is a FEATURE report type. */\r
                        };\r
                        \r

-                       /** Enum for the possible error codes in the return value of the ProcessHIDReport() function */\r
+                       /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */\r

                        enum HID_Parse_ErrorCodes_t\r
                        {\r
                                HID_PARSE_Successful                  = 0, /**< Successful parse of the HID report descriptor, no error. */\r
                        enum HID_Parse_ErrorCodes_t\r
                        {\r
                                HID_PARSE_Successful                  = 0, /**< Successful parse of the HID report descriptor, no error. */\r

-                               HID_PARSE_HIDStackOverflow            = 1, /**< More than HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ \r
+                               HID_PARSE_HIDStackOverflow            = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ \r

                                HID_PARSE_HIDStackUnderflow           = 2, /**< A POP was found when the state table stack was empty. */\r
                                HID_PARSE_HIDStackUnderflow           = 2, /**< A POP was found when the state table stack was empty. */\r

-                               HID_PARSE_InsufficientReportItems     = 3, /**< More than HID_MAX_REPORTITEMS report items in the report. */\r
+                               HID_PARSE_InsufficientReportItems     = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */\r

                                HID_PARSE_UnexpectedEndCollection     = 4, /**< END COLLECTION found without matching COLLECTION item. */\r
                                HID_PARSE_UnexpectedEndCollection     = 4, /**< END COLLECTION found without matching COLLECTION item. */\r

-                               HID_PARSE_InsufficientCollectionPaths = 5, /**< More than HID_MAX_COLLECTIONS collections in the report. */\r
-                               HID_PARSE_UsageStackOverflow          = 6, /**< More than HID_USAGE_STACK_DEPTH usages listed in a row. */\r
+                               HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */\r
+                               HID_PARSE_UsageStackOverflow          = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */\r

                        };\r
                \r
                /* Type Defines: */             \r
                        };\r
                \r
                /* Type Defines: */             \r


@@ -153,7 +162,7 @@
                         */\r
                        typedef struct CollectionPath\r
                        {\r
                         */\r
                        typedef struct CollectionPath\r
                        {\r

-                               uint8_t                      Type;   /**< Collection type (for example "Generic Desktop"). */\r
+                               uint8_t                      Type;   /**< Collection type (e.g. "Generic Desktop"). */\r

                                HID_Usage_t                  Usage;  /**< Collection usage. */\r
                                struct CollectionPath*       Parent; /**< Reference to parent collection, or NULL if root collection. */\r
                        } HID_CollectionPath_t;\r
                                HID_Usage_t                  Usage;  /**< Collection usage. */\r
                                struct CollectionPath*       Parent; /**< Reference to parent collection, or NULL if root collection. */\r
                        } HID_CollectionPath_t;\r


@@ -198,40 +207,40 @@
                        \r
                /* Function Prototypes: */\r
                        /** Function to process a given HID report returned from an attached device, and store it into a given\r
                        \r
                /* Function Prototypes: */\r
                        /** Function to process a given HID report returned from an attached device, and store it into a given\r

-                        *  HID_ReportInfo_t structure.\r
+                        *  \ref HID_ReportInfo_t structure.\r

                         *\r
                         *  \param ReportData  Buffer containing the device's HID report table\r
                         *  \param ReportSize  Size in bytes of the HID report table\r
                         *\r
                         *  \param ReportData  Buffer containing the device's HID report table\r
                         *  \param ReportSize  Size in bytes of the HID report table\r

-                        *  \param ParserData  Pointer to a HID_ReportInfo_t instance for the parser output\r
+                        *  \param ParserData  Pointer to a \ref HID_ReportInfo_t instance for the parser output\r

                         *\r
                         *\r

-                        *  \return A value in the HID_Parse_ErrorCodes_t enum\r
+                        *  \return A value in the \ref HID_Parse_ErrorCodes_t enum\r

                         */\r
                         */\r

-                       uint8_t ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)\r
-                                                ATTR_NON_NULL_PTR_ARG(1, 3);\r
+                       uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)\r
+                                                    ATTR_NON_NULL_PTR_ARG(1, 3);\r

 \r
                        /** Extracts the given report item's value out of the given HID report and places it into the Value\r
 \r
                        /** Extracts the given report item's value out of the given HID report and places it into the Value\r

-                        *  member of the report item's HID_ReportItem_t structure.\r
+                        *  member of the report item's \ref HID_ReportItem_t structure.\r

                         *\r
                         *  \param ReportData  Buffer containing an IN or FEATURE report from an attached device\r
                         *\r
                         *  \param ReportData  Buffer containing an IN or FEATURE report from an attached device\r

-                        *  \param ReportItem  Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array\r
+                        *  \param ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r

                         *\r
                         *  \returns Boolean true if the item to retrieve was located in the given report, false otherwise\r
                         */\r
                         *\r
                         *  \returns Boolean true if the item to retrieve was located in the given report, false otherwise\r
                         */\r

-                       bool GetReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)\r
-                                              ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                       bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)\r
+                                                     ATTR_NON_NULL_PTR_ARG(1, 2);\r

 \r
 \r

-                       /** Retreives the given report item's value out of the Value member of the report item's\r
-                        *  HID_ReportItem_t structure and places it into the correct position in the HID report\r
+                       /** Retrieves the given report item's value out of the Value member of the report item's\r
+                        *  \ref HID_ReportItem_t structure and places it into the correct position in the HID report\r

                         *  buffer. The report buffer is assumed to have the appropriate bits cleared before calling\r
                         *  this function (i.e., the buffer should be explicitly cleared before report values are added).\r
                         *\r
                         *  If the device has multiple HID reports, the report ID is set to the report ID of the given item.\r
                         *\r
                         *  \param ReportData  Buffer holding the current OUT report data\r
                         *  buffer. The report buffer is assumed to have the appropriate bits cleared before calling\r
                         *  this function (i.e., the buffer should be explicitly cleared before report values are added).\r
                         *\r
                         *  If the device has multiple HID reports, the report ID is set to the report ID of the given item.\r
                         *\r
                         *  \param ReportData  Buffer holding the current OUT report data\r

-                        *  \param ReportItem  Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array\r
+                        *  \param ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r

                         */\r
                         */\r

-                       void SetReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem)\r
-                                              ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                       void USB_SetHIDReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem)\r
+                                                     ATTR_NON_NULL_PTR_ARG(1, 2);\r

 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r
 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r


@@ -250,3 +259,5 @@
                #endif\r
 \r
 #endif\r
                #endif\r
 \r
 #endif\r

+\r
+/** @} */\r