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

tmk_core/common/avr/bootloader.c

@@ -13,12 +13,11 @@
 #endif
 
 
-/* Bootloader Size in *bytes*
+/** \brief Bootloader Size in *bytes*
  *
  * AVR Boot section size are defined by setting BOOTSZ fuse in fact. Consult with your MCU datasheet.
  * Note that 'Word'(2 bytes) size and address are used in datasheet while TMK uses 'Byte'.
  *
- *
  * Size of Bootloaders in bytes:
  *   Atmel DFU loader(ATmega32U4)   4096
  *   Atmel DFU loader(AT90USB128)   8192
@@ -28,10 +27,8 @@
  *   Teensy   halfKay(ATmega32U4)   512
  *   Teensy++ halfKay(AT90USB128)   1024
  *
- *
  * AVR Boot section is located at the end of Flash memory like the followings.
  *
- *
  * byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB128)
  * 0x0000   +---------------+               0x00000  +---------------+
  *          |               |                        |               |
@@ -57,7 +54,6 @@
  *          |  Bootloader   | 512B                   |  Bootloader   | 1KB
  * 0x7FFF   +---------------+               0x1FFFF  +---------------+
  */
-
 #define FLASH_SIZE (FLASHEND + 1L)
 
 #if !defined(BOOTLOADER_SIZE)
@@ -69,14 +65,17 @@
 #define BOOT_SIZE_1024 0b010
 #define BOOT_SIZE_2048 0b000
 
-/*
- * Entering the Bootloader via Software
+/** \brief Entering the Bootloader via Software
+ *
  * http://www.fourwalledcubicle.com/files/LUFA/Doc/120730/html/_page__software_bootloader_start.html
  */
 #define BOOTLOADER_RESET_KEY 0xB007B007
 uint32_t reset_key  __attribute__ ((section (".noinit")));
 
-/* initialize MCU status by watchdog reset */
+/** \brief initialize MCU status by watchdog reset 
+ *
+ * FIXME: needs doc
+ */
 void bootloader_jump(void) {
 
     #if !defined(BOOTLOADER_SIZE)

tmk_core/common/avr/sleep_led.c

@@ -18,6 +18,10 @@
  */
 #define SLEEP_LED_TIMER_TOP F_CPU/(256*64)
 
+/** \brief Sleep LED initialization
+ *
+ * FIXME: needs doc
+ */
 void sleep_led_init(void)
 {
     /* Timer1 setup */
@@ -33,18 +37,30 @@ void sleep_led_init(void)
     SREG = sreg;
 }
 
+/** \brief Sleep LED enable
+ *
+ * FIXME: needs doc
+ */
 void sleep_led_enable(void)
 {
     /* Enable Compare Match Interrupt */
     TIMSK1 |= _BV(OCIE1A);
 }
 
+/** \brief Sleep LED disable
+ *
+ * FIXME: needs doc
+ */
 void sleep_led_disable(void)
 {
     /* Disable Compare Match Interrupt */
     TIMSK1 &= ~_BV(OCIE1A);
 }
 
+/** \brief Sleep LED toggle
+ *
+ * FIXME: needs doc
+ */
 void sleep_led_toggle(void)
 {
     /* Disable Compare Match Interrupt */
@@ -52,7 +68,8 @@ void sleep_led_toggle(void)
 }
 
 
-/* Breathing Sleep LED brighness(PWM On period) table
+/** \brief Breathing Sleep LED brighness(PWM On period) table
+ *
  * (64[steps] * 4[duration]) / 64[PWM periods/s] = 4 second breath cycle
  *
  * http://www.wolframalpha.com/input/?i=%28sin%28+x%2F64*pi%29**8+*+255%2C+x%3D0+to+63

tmk_core/common/avr/suspend.c

@@ -41,6 +41,10 @@ __asm__ __volatile__ (  \
 )
 
 
+/** \brief Suspend idle
+ *
+ * FIXME: needs doc
+ */
 void suspend_idle(uint8_t time)
 {
     cli();
@@ -52,7 +56,8 @@ void suspend_idle(uint8_t time)
 }
 
 #ifndef NO_SUSPEND_POWER_DOWN
-/* Power down MCU with watchdog timer
+/** \brief Power down MCU with watchdog timer
+ *
  * wdto: watchdog timer timeout defined in <avr/wdt.h>
  *          WDTO_15MS
  *          WDTO_30MS
@@ -67,6 +72,10 @@ void suspend_idle(uint8_t time)
  */
 static uint8_t wdt_timeout = 0;
 
+/** \brief Power down
+ *
+ * FIXME: needs doc
+ */
 static void power_down(uint8_t wdto)
 {
 #ifdef PROTOCOL_LUFA
@@ -111,6 +120,10 @@ static void power_down(uint8_t wdto)
 }
 #endif
 
+/** \brief Suspend power down
+ *
+ * FIXME: needs doc
+ */
 void suspend_power_down(void)
 {
 #ifndef NO_SUSPEND_POWER_DOWN
@@ -131,7 +144,10 @@ bool suspend_wakeup_condition(void)
      return false;
 }
 
-// run immediately after wakeup
+/** \brief run immediately after wakeup
+ *
+ * FIXME: needs doc
+ */
 void suspend_wakeup_init(void)
 {
     // clear keyboard state

tmk_core/common/avr/timer.c

@@ -27,6 +27,10 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 // NOTE: union { uint32_t timer32; struct { uint16_t dummy; uint16_t timer16; }}
 volatile uint32_t timer_count;
 
+/** \brief timer initialization
+ *
+ * FIXME: needs doc
+ */
 void timer_init(void)
 {
 #if TIMER_PRESCALER == 1
@@ -60,6 +64,10 @@ void timer_init(void)
 #endif
 }
 
+/** \brief timer clear
+ *
+ * FIXME: needs doc
+ */
 inline
 void timer_clear(void)
 {
@@ -68,6 +76,10 @@ void timer_clear(void)
   }
 }
 
+/** \brief timer read
+ *
+ * FIXME: needs doc
+ */
 inline
 uint16_t timer_read(void)
 {
@@ -80,6 +92,10 @@ uint16_t timer_read(void)
     return (t & 0xFFFF);
 }
 
+/** \brief timer read32
+ *
+ * FIXME: needs doc
+ */
 inline
 uint32_t timer_read32(void)
 {
@@ -92,6 +108,10 @@ uint32_t timer_read32(void)
     return t;
 }
 
+/** \brief timer elapsed
+ *
+ * FIXME: needs doc
+ */
 inline
 uint16_t timer_elapsed(uint16_t last)
 {
@@ -104,6 +124,10 @@ uint16_t timer_elapsed(uint16_t last)
     return TIMER_DIFF_16((t & 0xFFFF), last);
 }
 
+/** \brief timer elapsed32
+ *
+ * FIXME: needs doc
+ */
 inline
 uint32_t timer_elapsed32(uint32_t last)
 {