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

3 files changed, 69 insertions, 1 deletions

diff --git a/tmk_core/common/chibios/bootloader.c b/tmk_core/common/chibios/bootloader.c
index 2dd3ade34e..f9895237b9 100644
--- a/tmk_core/common/chibios/bootloader.c
+++ b/tmk_core/common/chibios/bootloader.c
@@ -13,11 +13,19 @@ extern uint32_t __ram0_end__;
 #define MAGIC_ADDR (unsigned long*)(SYMVAL(__ram0_end__) - 4)
 
 
+/** \brief Jump to the bootloader
+ *
+ * FIXME: needs doc
+ */
 void bootloader_jump(void) {
   *MAGIC_ADDR = BOOTLOADER_MAGIC; // set magic flag => reset handler will jump into boot loader
    NVIC_SystemReset();
 }
 
+/** \brief Enter bootloader mode if requested
+ *
+ * FIXME: needs doc
+ */
 void enter_bootloader_mode_if_requested(void)  {
   unsigned long* check = MAGIC_ADDR;
   if(*check == BOOTLOADER_MAGIC)  {
diff --git a/tmk_core/common/chibios/eeprom.c b/tmk_core/common/chibios/eeprom.c
index 5ff8ee86f4..9061b790c4 100644
--- a/tmk_core/common/chibios/eeprom.c
+++ b/tmk_core/common/chibios/eeprom.c
@@ -79,6 +79,10 @@
   #define EEESIZE 0x39
 #endif
 
+/** \brief eeprom initialization
+ *
+ * FIXME: needs doc
+ */
 void eeprom_initialize(void)
 {
 	uint32_t count=0;
@@ -111,6 +115,10 @@ void eeprom_initialize(void)
 
 #define FlexRAM ((uint8_t *)0x14000000)
 
+/** \brief eeprom read byte
+ *
+ * FIXME: needs doc
+ */
 uint8_t eeprom_read_byte(const uint8_t *addr)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -119,6 +127,10 @@ uint8_t eeprom_read_byte(const uint8_t *addr)
 	return FlexRAM[offset];
 }
 
+/** \brief eeprom read word
+ *
+ * FIXME: needs doc
+ */
 uint16_t eeprom_read_word(const uint16_t *addr)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -127,6 +139,10 @@ uint16_t eeprom_read_word(const uint16_t *addr)
 	return *(uint16_t *)(&FlexRAM[offset]);
 }
 
+/** \brief eeprom read dword
+ *
+ * FIXME: needs doc
+ */
 uint32_t eeprom_read_dword(const uint32_t *addr)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -135,6 +151,10 @@ uint32_t eeprom_read_dword(const uint32_t *addr)
 	return *(uint32_t *)(&FlexRAM[offset]);
 }
 
+/** \brief eeprom read block
+ *
+ * FIXME: needs doc
+ */
 void eeprom_read_block(void *buf, const void *addr, uint32_t len)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -148,11 +168,19 @@ void eeprom_read_block(void *buf, const void *addr, uint32_t len)
 	}
 }
 
+/** \brief eeprom is ready
+ *
+ * FIXME: needs doc
+ */
 int eeprom_is_ready(void)
 {
 	return (FTFL->FCNFG & FTFL_FCNFG_EEERDY) ? 1 : 0;
 }
 
+/** \brief flexram wait
+ *
+ * FIXME: needs doc
+ */
 static void flexram_wait(void)
 {
 	while (!(FTFL->FCNFG & FTFL_FCNFG_EEERDY)) {
@@ -160,6 +188,10 @@ static void flexram_wait(void)
 	}
 }
 
+/** \brief eeprom_write_byte
+ *
+ * FIXME: needs doc
+ */
 void eeprom_write_byte(uint8_t *addr, uint8_t value)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -172,6 +204,10 @@ void eeprom_write_byte(uint8_t *addr, uint8_t value)
 	}
 }
 
+/** \brief eeprom write word
+ *
+ * FIXME: needs doc
+ */
 void eeprom_write_word(uint16_t *addr, uint16_t value)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -199,6 +235,10 @@ void eeprom_write_word(uint16_t *addr, uint16_t value)
 #endif
 }
 
+/** \brief eeprom write dword
+ *
+ * FIXME: needs doc
+ */
 void eeprom_write_dword(uint32_t *addr, uint32_t value)
 {
 	uint32_t offset = (uint32_t)addr;
@@ -242,6 +282,10 @@ void eeprom_write_dword(uint32_t *addr, uint32_t value)
 #endif
 }
 
+/** \brief eeprom write block
+ *
+ * FIXME: needs doc
+ */
 void eeprom_write_block(const void *buf, void *addr, uint32_t len)
 {
 	uint32_t offset = (uint32_t)addr;
diff --git a/tmk_core/common/chibios/suspend.c b/tmk_core/common/chibios/suspend.c
index 7c3c75387d..32ef773e2e 100644
--- a/tmk_core/common/chibios/suspend.c
+++ b/tmk_core/common/chibios/suspend.c
@@ -12,11 +12,19 @@
 #include "suspend.h"
 #include "wait.h"
 
+/** \brief suspend idle
+ *
+ * FIXME: needs doc
+ */
 void suspend_idle(uint8_t time) {
 	// TODO: this is not used anywhere - what units is 'time' in?
 	wait_ms(time);
 }
 
+/** \brief suspend power down
+ *
+ * FIXME: needs doc
+ */
 void suspend_power_down(void) {
 	// TODO: figure out what to power down and how
 	// shouldn't power down TPM/FTM if we want a breathing LED
@@ -28,6 +36,10 @@ void suspend_power_down(void) {
 	wait_ms(17);
 }
 
+/** \brief suspend wakeup condition
+ *
+ * FIXME: needs doc
+ */
 __attribute__ ((weak)) void matrix_power_up(void) {}
 __attribute__ ((weak)) void matrix_power_down(void) {}
 bool suspend_wakeup_condition(void)
@@ -41,7 +53,11 @@ bool suspend_wakeup_condition(void)
     return false;
 }
 
-// run immediately after wakeup
+/** \brief suspend wakeup condition
+ *
+ * run immediately after wakeup
+ * FIXME: needs doc
+ */
 void suspend_wakeup_init(void)
 {
     // clear keyboard state