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/avr/bootloader.c | 15 +++++++-------- tmk_core/common/avr/sleep_led.c | 19 ++++++++++++++++++- tmk_core/common/avr/suspend.c | 20 ++++++++++++++++++-- tmk_core/common/avr/timer.c | 24 ++++++++++++++++++++++++ 4 files changed, 67 insertions(+), 11 deletions(-) (limited to 'tmk_core/common/avr') diff --git a/tmk_core/common/avr/bootloader.c b/tmk_core/common/avr/bootloader.c index ee150817c3..d89c8d768d 100644 --- a/tmk_core/common/avr/bootloader.c +++ b/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) diff --git a/tmk_core/common/avr/sleep_led.c b/tmk_core/common/avr/sleep_led.c index dab3eb0f3c..0cb774c81f 100644 --- a/tmk_core/common/avr/sleep_led.c +++ b/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 diff --git a/tmk_core/common/avr/suspend.c b/tmk_core/common/avr/suspend.c index 213f03f6fa..4cdd6a420e 100644 --- a/tmk_core/common/avr/suspend.c +++ b/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 * 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 diff --git a/tmk_core/common/avr/timer.c b/tmk_core/common/avr/timer.c index 369015200d..b7d4f060ef 100644 --- a/tmk_core/common/avr/timer.c +++ b/tmk_core/common/avr/timer.c @@ -27,6 +27,10 @@ along with this program. If not, see . // 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) { -- cgit v1.2.3