From 7c9d5ace143d3cc6d767a354acde814926d566fd Mon Sep 17 00:00:00 2001 From: skullydazed Date: Wed, 21 Mar 2018 23:50:38 -0700 Subject: 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/chibios/bootloader.c | 8 +++++++ tmk_core/common/chibios/eeprom.c | 44 ++++++++++++++++++++++++++++++++++++ tmk_core/common/chibios/suspend.c | 18 ++++++++++++++- 3 files changed, 69 insertions(+), 1 deletion(-) (limited to 'tmk_core/common/chibios') 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 -- cgit v1.2.3