Generate API docs from source code comments (#2491)

[qmk_firmware.git] / tmk_core / protocol / lufa / lufa.c

diff --git a/tmk_core/protocol/lufa/lufa.c b/tmk_core/protocol/lufa/lufa.c
index a1cab98a66abd18c9a580c3859427a0d45d9562a..cb918d3dce1453f4f11d16810480cf39d7c41eea 100644 (file)
--- a/tmk_core/protocol/lufa/lufa.c
+++ b/tmk_core/protocol/lufa/lufa.c
@@ -141,6 +141,10 @@ USB_ClassInfo_CDC_Device_t cdc_device =
 
 #ifdef RAW_ENABLE
 
+/** \brief Raw HID Send
+ *
+ * FIXME: Needs doc
+ */
 void raw_hid_send( uint8_t *data, uint8_t length )
 {
        // TODO: implement variable size packet
@@ -172,6 +176,10 @@ void raw_hid_send( uint8_t *data, uint8_t length )
        Endpoint_SelectEndpoint(ep);
 }
 
+/** \brief Raw HID Receive
+ *
+ * FIXME: Needs doc
+ */
 __attribute__ ((weak))
 void raw_hid_receive( uint8_t *data, uint8_t length )
 {
@@ -180,6 +188,10 @@ void raw_hid_receive( uint8_t *data, uint8_t length )
        // so users can opt to not handle data coming in.
 }
 
+/** \brief Raw HID Task
+ *
+ * FIXME: Needs doc
+ */
 static void raw_hid_task(void)
 {
        // Create a temporary buffer to hold the read in data from the host
@@ -218,6 +230,10 @@ static void raw_hid_task(void)
  * Console
  ******************************************************************************/
 #ifdef CONSOLE_ENABLE
+/** \brief Console Task
+ *
+ * FIXME: Needs doc
+ */
 static void Console_Task(void)
 {
     /* Device must be connected and configured for the task to run */
@@ -282,6 +298,10 @@ static void Console_Task(void)
  * 2) EVENT_USB_Device_Reset
  * 3) EVENT_USB_Device_Wake
 */
+/** \brief Event USB Device Connect
+ *
+ * FIXME: Needs doc
+ */
 void EVENT_USB_Device_Connect(void)
 {
     print("[C]");
@@ -293,6 +313,10 @@ void EVENT_USB_Device_Connect(void)
     }
 }
 
+/** \brief Event USB Device Connect
+ *
+ * FIXME: Needs doc
+ */
 void EVENT_USB_Device_Disconnect(void)
 {
     print("[D]");
@@ -307,11 +331,19 @@ void EVENT_USB_Device_Disconnect(void)
 */
 }
 
+/** \brief Event USB Device Connect
+ *
+ * FIXME: Needs doc
+ */
 void EVENT_USB_Device_Reset(void)
 {
     print("[R]");
 }
 
+/** \brief Event USB Device Connect
+ *
+ * FIXME: Needs doc
+ */
 void EVENT_USB_Device_Suspend()
 {
     print("[S]");
@@ -320,6 +352,10 @@ void EVENT_USB_Device_Suspend()
 #endif
 }
 
+/** \brief Event USB Device Connect
+ *
+ * FIXME: Needs doc
+ */
 void EVENT_USB_Device_WakeUp()
 {
     print("[W]");
@@ -342,7 +378,11 @@ static bool console_flush = false;
   } \
 } while (0)
 
-// called every 1ms
+/** \brief Event USB Device Start Of Frame
+ *
+ * FIXME: Needs doc
+ * called every 1ms
+ */
 void EVENT_USB_Device_StartOfFrame(void)
 {
     static uint8_t count;
@@ -356,11 +396,12 @@ void EVENT_USB_Device_StartOfFrame(void)
 
 #endif
 
-/** Event handler for the USB_ConfigurationChanged event.
+/** \brief Event handler for the USB_ConfigurationChanged event.
+ *
  * This is fired when the host sets the current configuration of the USB device after enumeration.
  *
  * ATMega32u2 supports dual bank(ping-pong mode) only on endpoint 3 and 4,
- * it is safe to use singl bank for all endpoints.
+ * it is safe to use single bank for all endpoints.
  */
 void EVENT_USB_Device_ConfigurationChanged(void)
 {
@@ -418,7 +459,7 @@ void EVENT_USB_Device_ConfigurationChanged(void)
 #endif
 }
 
-/*
+/* FIXME: Expose this table in the docs somehow
 Appendix G: HID Request Support Requirements
 
 The following table enumerates the requests that need to be supported by various types of HID class devices.
@@ -431,7 +472,8 @@ Boot Keyboard   Required    Optional    Required    Required    Required    Requ
 Non-Boot Keybrd Required    Optional    Required    Required    Optional    Optional
 Other Device    Required    Optional    Optional    Optional    Optional    Optional
 */
-/** Event handler for the USB_ControlRequest event.
+/** \brief Event handler for the USB_ControlRequest event.
+ *
  *  This is fired before passing along unhandled control requests to the library for processing internally.
  */
 void EVENT_USB_Device_ControlRequest(void)
@@ -546,11 +588,19 @@ void EVENT_USB_Device_ControlRequest(void)
 /*******************************************************************************
  * Host driver
  ******************************************************************************/
+/** \brief Keyboard LEDs
+ *
+ * FIXME: Needs doc
+ */
 static uint8_t keyboard_leds(void)
 {
     return keyboard_led_stats;
 }
 
+/** \brief Send Keyboard
+ *
+ * FIXME: Needs doc
+ */
 static void send_keyboard(report_keyboard_t *report)
 {
     uint8_t timeout = 255;
@@ -612,7 +662,11 @@ static void send_keyboard(report_keyboard_t *report)
 
     keyboard_report_sent = *report;
 }
-
+ 
+/** \brief Send Mouse
+ *
+ * FIXME: Needs doc
+ */
 static void send_mouse(report_mouse_t *report)
 {
 #ifdef MOUSE_ENABLE
@@ -657,6 +711,10 @@ static void send_mouse(report_mouse_t *report)
 #endif
 }
 
+/** \brief Send System
+ *
+ * FIXME: Needs doc
+ */
 static void send_system(uint16_t data)
 {
     uint8_t timeout = 255;
@@ -678,6 +736,10 @@ static void send_system(uint16_t data)
     Endpoint_ClearIN();
 }
 
+/** \brief Send Consumer
+ *
+ * FIXME: Needs doc
+ */
 static void send_consumer(uint16_t data)
 {
     uint8_t timeout = 255;
@@ -739,6 +801,10 @@ static void send_consumer(uint16_t data)
  ******************************************************************************/
 #ifdef CONSOLE_ENABLE
 #define SEND_TIMEOUT 5
+/** \brief Send Char
+ *
+ * FIXME: Needs doc
+ */
 int8_t sendchar(uint8_t c)
 {
     // Not wait once timeouted.
@@ -842,18 +908,30 @@ bool recv_midi_packet(MIDI_EventPacket_t* const event) {
  ******************************************************************************/
 
 #ifdef VIRTSER_ENABLE
+/** \brief Virtual Serial Init
+ *
+ * FIXME: Needs doc
+ */
 void virtser_init(void)
 {
   cdc_device.State.ControlLineStates.DeviceToHost = CDC_CONTROL_LINE_IN_DSR ;
   CDC_Device_SendControlLineStateChange(&cdc_device);
 }
 
+/** \brief Virtual Serial Receive
+ *
+ * FIXME: Needs doc
+ */
 void virtser_recv(uint8_t c) __attribute__ ((weak));
 void virtser_recv(uint8_t c)
 {
   // Ignore by default
 }
 
+/** \brief Virtual Serial Task
+ *
+ * FIXME: Needs doc
+ */
 void virtser_task(void)
 {
   uint16_t count = CDC_Device_BytesReceived(&cdc_device);
@@ -864,6 +942,10 @@ void virtser_task(void)
     virtser_recv(ch);
   }
 }
+/** \brief Virtual Serial Send
+ *
+ * FIXME: Needs doc
+ */
 void virtser_send(const uint8_t byte)
 {
   uint8_t timeout = 255;
@@ -896,6 +978,10 @@ void virtser_send(const uint8_t byte)
 /*******************************************************************************
  * main
  ******************************************************************************/
+/** \brief Setup MCU
+ *
+ * FIXME: Needs doc
+ */
 static void setup_mcu(void)
 {
     /* Disable watchdog if enabled by bootloader/fuses */
@@ -909,6 +995,10 @@ static void setup_mcu(void)
     CLKPR = (0 << CLKPS3) | (0 << CLKPS2) | (0 << CLKPS1) | (0 << CLKPS0);
 }
 
+/** \brief Setup USB
+ *
+ * FIXME: Needs doc
+ */
 static void setup_usb(void)
 {
     // Leonardo needs. Without this USB device is not recognized.
@@ -921,6 +1011,10 @@ static void setup_usb(void)
     print_set_sendchar(sendchar);
 }
 
+/** \brief Main
+ *
+ * FIXME: Needs doc
+ */
 int main(void)  __attribute__ ((weak));
 int main(void)
 {