Minor documentation page updates.

[pub/USBasp.git] / Projects / Magstripe / Magstripe.c

diff --git a/Projects/Magstripe/Magstripe.c b/Projects/Magstripe/Magstripe.c
index 871db28..e32397c 100644 (file)
--- a/Projects/Magstripe/Magstripe.c
+++ b/Projects/Magstripe/Magstripe.c
@@ -29,10 +29,23 @@
   this software.\r
 */\r
  \r
+/** \file\r
+ *\r
+ *  Main source file for the MagStripe reader program. This file contains the main tasks of\r
+ *  the project and is responsible for the initial application hardware configuration.\r
+ */\r
+ \r
 #include "Magstripe.h"\r
 \r
+/** Bit buffers to hold the read bits for each of the three magnetic card tracks before they are transmitted\r
+ *  to the host as keyboard presses.\r
+ */\r
 BitBuffer_t TrackDataBuffers[3];\r
 \r
+/** LUFA HID Class driver interface configuration and state information. This structure is\r
+ *  passed to all HID Class driver functions, so that multiple instances of the same class\r
+ *  within a device can be differentiated from one another.\r
+ */\r
 USB_ClassInfo_HID_t Keyboard_HID_Interface =\r
        {\r
                .InterfaceNumber         = 0,\r
@@ -43,6 +56,9 @@ USB_ClassInfo_HID_t Keyboard_HID_Interface =
                .ReportINBufferSize      = sizeof(USB_KeyboardReport_Data_t),\r
        };\r
 \r
+/** Main program entry point. This routine contains the overall program flow, including initial\r
+ *  setup of all components and the main program loop.\r
+ */\r
 int main(void)\r
 {\r
        SetupHardware();\r
@@ -60,6 +76,7 @@ int main(void)
        }\r
 }\r
 \r
+/** Configures the board hardware and chip peripherals for the demo's functionality. */\r
 void SetupHardware(void)\r
 {\r
        /* Disable watchdog if enabled by bootloader/fuses */\r
@@ -80,6 +97,9 @@ void SetupHardware(void)
        TIMSK0 = (1 << OCIE0A);\r
 }\r
 \r
+/** Determines if a card has been inserted, and if so reads in each track's contents into the bit buffers\r
+ *  until they are read out to the host as a series of keyboard presses.\r
+ */\r
 void ReadMagstripeData(void)\r
 {\r
        /* Arrays to hold the buffer pointers, clock and data bit masks for the separate card tracks */\r
@@ -111,22 +131,32 @@ void ReadMagstripeData(void)
        }\r
 }\r
 \r
+/** Event handler for the library USB Configuration Changed event. */\r
 void EVENT_USB_ConfigurationChanged(void)\r
 {\r
        USB_HID_ConfigureEndpoints(&Keyboard_HID_Interface);\r
 }\r
 \r
+/** Event handler for the library USB Unhandled Control Packet event. */\r
 void EVENT_USB_UnhandledControlPacket(void)\r
 {\r
        USB_HID_ProcessControlPacket(&Keyboard_HID_Interface);\r
 }\r
 \r
+/** Timer 0 CTC ISR, firing once each millisecond to keep track of elapsed idle time in the HID interface. */\r
 ISR(TIMER0_COMPA_vect, ISR_BLOCK)\r
 {\r
        if (Keyboard_HID_Interface.IdleMSRemaining)\r
          Keyboard_HID_Interface.IdleMSRemaining--;\r
 }\r
 \r
+/** HID Class driver callback function for the creation of a HID report for the host.\r
+ *\r
+ *  \param HIDInterfaceInfo  Pointer to the HID interface structure for the HID interface being referenced\r
+ *  \param ReportData  Pointer to the preallocated report buffer where the created report should be stored\r
+ *\r
+ *  \return Number of bytes in the created report\r
+ */\r
 uint16_t CALLBACK_USB_HID_CreateNextHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData)\r
 {\r
        static bool IsKeyReleaseReport;\r
@@ -168,6 +198,12 @@ uint16_t CALLBACK_USB_HID_CreateNextHIDReport(USB_ClassInfo_HID_t* HIDInterfaceI
        return sizeof(USB_KeyboardReport_Data_t);\r
 }\r
 \r
+/** HID Class driver callback function for the processing of a received HID report from the host.\r
+ *\r
+ *  \param HIDInterfaceInfo  Pointer to the HID interface structure for the HID interface being referenced\r
+ *  \param ReportData  Pointer to the report buffer where the received report is stored\r
+ *  \param ReportSize  Size in bytes of the report received from the host\r
+ */\r
 void CALLBACK_USB_HID_ProcessReceivedHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData, uint16_t ReportSize)\r
 {\r
        // Unused (but mandatory for the HID class driver) in this demo, since there are no Host->Device reports\r