Minor documentation corrections.

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

diff --git a/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h b/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h
index 95b3484..c3fe3ed 100644 (file)
--- a/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h
+++ b/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h
@@ -1,13 +1,13 @@
 /*
              LUFA Library
 /*
              LUFA Library

-     Copyright (C) Dean Camera, 2011.
+     Copyright (C) Dean Camera, 2012.

 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*
 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*

-  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2012  Dean Camera (dean [at] fourwalledcubicle [dot] com)

 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted


@@ -91,7 +91,7 @@
                /** Constant for a keyboard report modifier byte, indicating that the keyboard's right GUI key is currently pressed. */
                #define HID_KEYBOARD_MODIFIER_RIGHTGUI                    (1 << 7)
                //@}
                /** Constant for a keyboard report modifier byte, indicating that the keyboard's right GUI key is currently pressed. */
                #define HID_KEYBOARD_MODIFIER_RIGHTGUI                    (1 << 7)
                //@}

-               
+

                /** \name Keyboard Standard Report LED Masks */
                //@{
                /** Constant for a keyboard output report LED byte, indicating that the host's NUM LOCK mode is currently set. */
                /** \name Keyboard Standard Report LED Masks */
                //@{
                /** Constant for a keyboard output report LED byte, indicating that the host's NUM LOCK mode is currently set. */


@@ -108,7 +108,7 @@
                //@}
 
                /** \name Keyboard Standard Report Key Scan-codes */
                //@}
 
                /** \name Keyboard Standard Report Key Scan-codes */

-               //@{    
+               //@{

                #define HID_KEYBOARD_SC_ERROR_ROLLOVER                    0x01
                #define HID_KEYBOARD_SC_POST_FAIL                         0x02
                #define HID_KEYBOARD_SC_ERROR_UNDEFINED                   0x03
                #define HID_KEYBOARD_SC_ERROR_ROLLOVER                    0x01
                #define HID_KEYBOARD_SC_POST_FAIL                         0x02
                #define HID_KEYBOARD_SC_ERROR_UNDEFINED                   0x03


@@ -208,7 +208,7 @@
                #define HID_KEYBOARD_SC_KEYPAD_9_AND_PAGE_UP              0x61
                #define HID_KEYBOARD_SC_KEYPAD_0_AND_INSERT               0x62
                #define HID_KEYBOARD_SC_KEYPAD_DOT_AND_DELETE             0x63
                #define HID_KEYBOARD_SC_KEYPAD_9_AND_PAGE_UP              0x61
                #define HID_KEYBOARD_SC_KEYPAD_0_AND_INSERT               0x62
                #define HID_KEYBOARD_SC_KEYPAD_DOT_AND_DELETE             0x63

-               #define HID_KEYBOARD_SC_NON_US_BACKSLASH_AND_PIPE         0x64          
+               #define HID_KEYBOARD_SC_NON_US_BACKSLASH_AND_PIPE         0x64

                #define HID_KEYBOARD_SC_POWER                             0x66
                #define HID_KEYBOARD_SC_EQUAL_SIGN                        0x67
                #define HID_KEYBOARD_SC_F13                               0x68
                #define HID_KEYBOARD_SC_POWER                             0x66
                #define HID_KEYBOARD_SC_EQUAL_SIGN                        0x67
                #define HID_KEYBOARD_SC_F13                               0x68


@@ -337,37 +337,36 @@
                 *  \code
                 *  struct
                 *  {
                 *  \code
                 *  struct
                 *  {

-                *      intB_t X; // Signed X axis value
-                *      intB_t Y; // Signed Y axis value
-                *      int8_t Z; // Signed Z axis value
-                *      // Additional axis elements here
-                *      uintA_t Buttons; // Pressed buttons bitmask
+                *      intA_t X; // Signed X axis value
+                *      intA_t Y; // Signed Y axis value
+                *      intA_t Z; // Signed Z axis value
+                *      uintB_t Buttons; // Pressed buttons bitmask

                 *  } Joystick_Report;
                 *  \endcode
                 *
                 *  } Joystick_Report;
                 *  \endcode
                 *

-                *  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.
+                *  Where \c uintA_t is a type large enough to hold the ranges of the signed \c MinAxisVal and \c MaxAxisVal values,
+                *  and \c intB_t is a type large enough to hold one bit per button.

                 *
                 *

-                *  \param[in] NumAxis         Number of axis in the joystick (8-bit)

                 *  \param[in] MinAxisVal      Minimum logical axis value (16-bit).
                 *  \param[in] MaxAxisVal      Maximum logical axis value (16-bit).
                 *  \param[in] MinPhysicalVal  Minimum physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] MaxPhysicalVal  Maximum physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] Buttons         Total number of buttons in the device (8-bit).
                 */
                 *  \param[in] MinAxisVal      Minimum logical axis value (16-bit).
                 *  \param[in] MaxAxisVal      Maximum logical axis value (16-bit).
                 *  \param[in] MinPhysicalVal  Minimum physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] MaxPhysicalVal  Maximum physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] Buttons         Total number of buttons in the device (8-bit).
                 */

-               #define HID_DESCRIPTOR_JOYSTICK(NumAxis, MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons) \
+               #define HID_DESCRIPTOR_JOYSTICK(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons) \

                        HID_RI_USAGE_PAGE(8, 0x01),                     \
                        HID_RI_USAGE(8, 0x04),                          \
                        HID_RI_COLLECTION(8, 0x01),                     \
                                HID_RI_USAGE(8, 0x01),                      \
                                HID_RI_COLLECTION(8, 0x00),                 \
                        HID_RI_USAGE_PAGE(8, 0x01),                     \
                        HID_RI_USAGE(8, 0x04),                          \
                        HID_RI_COLLECTION(8, 0x01),                     \
                                HID_RI_USAGE(8, 0x01),                      \
                                HID_RI_COLLECTION(8, 0x00),                 \

-                                       HID_RI_USAGE_MINIMUM(8, 0x30),          \
-                                       HID_RI_USAGE_MAXIMUM(8, (0x30 + (NumAxis - 1))), \
+                                       HID_RI_USAGE(8, 0x30),                  \
+                                       HID_RI_USAGE(8, 0x31),                  \
+                                       HID_RI_USAGE(8, 0x32),                  \

                                        HID_RI_LOGICAL_MINIMUM(16, MinAxisVal), \
                                        HID_RI_LOGICAL_MAXIMUM(16, MaxAxisVal), \
                                        HID_RI_PHYSICAL_MINIMUM(16, MinPhysicalVal), \
                                        HID_RI_PHYSICAL_MAXIMUM(16, MaxPhysicalVal), \
                                        HID_RI_LOGICAL_MINIMUM(16, MinAxisVal), \
                                        HID_RI_LOGICAL_MAXIMUM(16, MaxAxisVal), \
                                        HID_RI_PHYSICAL_MINIMUM(16, MinPhysicalVal), \
                                        HID_RI_PHYSICAL_MAXIMUM(16, MaxPhysicalVal), \

-                                       HID_RI_REPORT_COUNT(8, NumAxis),        \
+                                       HID_RI_REPORT_COUNT(8, 3),              \

                                        HID_RI_REPORT_SIZE(8, ((((MinAxisVal >= -0xFF) && (MaxAxisVal <= 0xFF)) ? 8 : 16))), \
                                        HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \
                                HID_RI_END_COLLECTION(0),                   \
                                        HID_RI_REPORT_SIZE(8, ((((MinAxisVal >= -0xFF) && (MaxAxisVal <= 0xFF)) ? 8 : 16))), \
                                        HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \
                                HID_RI_END_COLLECTION(0),                   \


@@ -392,7 +391,7 @@
                 *  \code
                 *  struct
                 *  {
                 *  \code
                 *  struct
                 *  {

-                *      uint8_t Modifier; // Keyboard modifier byte indicating pressed modifier keys (HID_KEYBOARD_MODIFER_* masks)
+                *      uint8_t Modifier; // Keyboard modifier byte indicating pressed modifier keys (\c HID_KEYBOARD_MODIFER_* masks)

                 *      uint8_t Reserved; // Reserved for OEM use, always set to 0.
                 *      uint8_t KeyCode[MaxKeys]; // Length determined by the number of keys that can be reported
                 *  } Keyboard_Report;
                 *      uint8_t Reserved; // Reserved for OEM use, always set to 0.
                 *      uint8_t KeyCode[MaxKeys]; // Length determined by the number of keys that can be reported
                 *  } Keyboard_Report;


@@ -456,7 +455,7 @@
                 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] Buttons         Total number of buttons in the device (8-bit).
                 *  \param[in] MinPhysicalVal  Minimum X/Y physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] MaxPhysicalVal  Maximum X/Y physical axis value, for movement resolution calculations (16-bit).
                 *  \param[in] Buttons         Total number of buttons in the device (8-bit).

-                *  \param[in] AbsoluteCoords  Boolean true to use absolute X/Y coordinates (e.g. touchscreen).
+                *  \param[in] AbsoluteCoords  Boolean \c 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),                     \
                 */
                #define HID_DESCRIPTOR_MOUSE(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons, AbsoluteCoords) \
                        HID_RI_USAGE_PAGE(8, 0x01),                     \


@@ -491,12 +490,12 @@
                /** \hideinitializer
                 *  A list of HID report item array elements that describe a typical Vendor Defined byte array HID report descriptor,
                 *  used for transporting arbitrary data between the USB host and device via HID reports. The resulting report should be
                /** \hideinitializer
                 *  A list of HID report item array elements that describe a typical Vendor Defined byte array HID report descriptor,
                 *  used for transporting arbitrary 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.
+                *  a \c 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 encompassing 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] VendorPageNum    Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF.
                 *  \param[in] CollectionUsage  Vendor Usage for the encompassing 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] 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) \
                 *  \param[in] NumBytes         Length of the data IN and OUT reports.
                 */
                #define HID_DESCRIPTOR_VENDOR(VendorPageNum, CollectionUsage, DataINUsage, DataOUTUsage, NumBytes) \


@@ -517,7 +516,7 @@
                                HID_RI_OUTPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE | HID_IOF_NON_VOLATILE), \
                        HID_RI_END_COLLECTION(0)
                //@}
                                HID_RI_OUTPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE | HID_IOF_NON_VOLATILE), \
                        HID_RI_END_COLLECTION(0)
                //@}

-               
+

        /* Type Defines: */
                /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the HID
                 *  device class.
        /* Type Defines: */
                /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the HID
                 *  device class.


@@ -543,7 +542,7 @@
                                                               *   belongs to the Mouse HID boot protocol.
                                                               */
                };
                                                               *   belongs to the Mouse HID boot protocol.
                                                               */
                };

-       
+

                /** Enum for the HID class specific control requests that can be issued by the USB bus host. */
                enum HID_ClassRequests_t
                {
                /** Enum for the HID class specific control requests that can be issued by the USB bus host. */
                enum HID_ClassRequests_t
                {