Generate API docs from source code comments (#2491)

* Generate api docs from source code

* Add a bunch of doxygen comments

* more doxygen comments

* Add the in-progress api docs

* script to generate docs from travis

* Add doc generation to the travis job

* make travis_docs.sh commit the work it does

* make sure the docs script exits cleanly

2 files changed, 116 insertions, 6 deletions

diff --git a/tmk_core/protocol/lufa/lufa.c b/tmk_core/protocol/lufa/lufa.c
index a1cab98a66..cb918d3dce 100644
--- 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)
 {
diff --git a/tmk_core/protocol/lufa/outputselect.c b/tmk_core/protocol/lufa/outputselect.c
index 0df5d3b75a..42de806120 100644
--- a/tmk_core/protocol/lufa/outputselect.c
+++ b/tmk_core/protocol/lufa/outputselect.c
@@ -20,15 +20,27 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 uint8_t desired_output = OUTPUT_DEFAULT;
 
+/** \brief Set Output
+ *
+ * FIXME: Needs doc
+ */
 void set_output(uint8_t output) {
     set_output_user(output);
     desired_output = output;
 }
 
+/** \brief Set Output User
+ *
+ * FIXME: Needs doc
+ */
 __attribute__((weak))
 void set_output_user(uint8_t output) {
 }
 
+/** \brief Auto Detect Output
+ *
+ * FIXME: Needs doc
+ */
 uint8_t auto_detect_output(void) {
     if (USB_DeviceState == DEVICE_STATE_Configured) {
         return OUTPUT_USB;
@@ -47,6 +59,10 @@ uint8_t auto_detect_output(void) {
     return OUTPUT_NONE;
 }
 
+/** \brief Where To Send
+ *
+ * FIXME: Needs doc
+ */
 uint8_t where_to_send(void) {
     if (desired_output == OUTPUT_AUTO) {
         return auto_detect_output();