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/action.c | 63 +++++++++++++++++-- tmk_core/common/action_code.h | 34 +++++----- tmk_core/common/action_layer.c | 101 ++++++++++++++++++++++++++++-- tmk_core/common/action_macro.c | 4 ++ tmk_core/common/action_tapping.c | 37 +++++++++-- tmk_core/common/action_util.c | 113 ++++++++++++++++++++++++++++++---- 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 ++++++++ tmk_core/common/backlight.c | 28 +++++++++ tmk_core/common/bootmagic.c | 14 ++++- tmk_core/common/bootmagic.h | 2 + tmk_core/common/chibios/bootloader.c | 8 +++ tmk_core/common/chibios/eeprom.c | 44 +++++++++++++ tmk_core/common/chibios/suspend.c | 18 +++++- tmk_core/common/command.h | 4 +- tmk_core/common/eeconfig.c | 56 +++++++++++++++++ tmk_core/common/keyboard.c | 32 +++++++++- tmk_core/common/keycode.h | 1 + tmk_core/common/led.h | 3 +- tmk_core/common/magic.c | 4 ++ tmk_core/common/report.c | 36 +++++++++++ tmk_core/protocol/lufa/lufa.c | 106 +++++++++++++++++++++++++++++-- tmk_core/protocol/lufa/outputselect.c | 16 +++++ 25 files changed, 732 insertions(+), 70 deletions(-) (limited to 'tmk_core') diff --git a/tmk_core/common/action.c b/tmk_core/common/action.c index 33d920554..fff834791 100644 --- a/tmk_core/common/action.c +++ b/tmk_core/common/action.c @@ -44,6 +44,10 @@ int retro_tapping_counter = 0; #include #endif +/** \brief Called to execute an action. + * + * FIXME: Needs documentation. + */ void action_exec(keyevent_t event) { if (!IS_NOEVENT(event)) { @@ -95,6 +99,10 @@ void action_exec(keyevent_t event) bool swap_hands = false; bool swap_held = false; +/** \brief Process Hand Swap + * + * FIXME: Needs documentation. + */ void process_hand_swap(keyevent_t *event) { static swap_state_row_t swap_state[MATRIX_ROWS]; @@ -134,7 +142,10 @@ bool process_record_quantum(keyrecord_t *record) { } #ifndef NO_ACTION_TAPPING -// Allows for handling tap-hold actions immediately instead of waiting for TAPPING_TERM or another keypress. +/** \brief Allows for handling tap-hold actions immediately instead of waiting for TAPPING_TERM or another keypress. + * + * FIXME: Needs documentation. + */ void process_record_tap_hint(keyrecord_t *record) { action_t action = layer_switch_get_action(record->event.key); @@ -154,6 +165,10 @@ void process_record_tap_hint(keyrecord_t *record) } #endif +/** \brief Take a key event (key press or key release) and processes it. + * + * FIXME: Needs documentation. + */ void process_record(keyrecord_t *record) { if (IS_NOEVENT(record->event)) { return; } @@ -172,6 +187,10 @@ void process_record(keyrecord_t *record) process_action(record, action); } +/** \brief Take an action and processes it. + * + * FIXME: Needs documentation. + */ void process_action(keyrecord_t *record, action_t action) { keyevent_t event = record->event; @@ -674,8 +693,9 @@ void process_action(keyrecord_t *record, action_t action) -/* - * Utilities for actions. +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. */ void register_code(uint8_t code) { @@ -755,6 +775,10 @@ void register_code(uint8_t code) } } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void unregister_code(uint8_t code) { if (code == KC_NO) { @@ -810,6 +834,10 @@ void unregister_code(uint8_t code) } } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void register_mods(uint8_t mods) { if (mods) { @@ -818,6 +846,10 @@ void register_mods(uint8_t mods) } } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void unregister_mods(uint8_t mods) { if (mods) { @@ -826,12 +858,20 @@ void unregister_mods(uint8_t mods) } } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void clear_keyboard(void) { clear_mods(); clear_keyboard_but_mods(); } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void clear_keyboard_but_mods(void) { clear_weak_mods(); @@ -848,6 +888,10 @@ void clear_keyboard_but_mods(void) #endif } +/** \brief Utilities for actions. (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ bool is_tap_key(keypos_t key) { action_t action = layer_switch_get_action(key); @@ -880,14 +924,19 @@ bool is_tap_key(keypos_t key) } -/* - * debug print +/** \brief Debug print (FIXME: Needs better description) + * + * FIXME: Needs documentation. */ void debug_event(keyevent_t event) { dprintf("%04X%c(%u)", (event.key.row<<8 | event.key.col), (event.pressed ? 'd' : 'u'), event.time); } +/** \brief Debug print (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void debug_record(keyrecord_t record) { debug_event(record.event); @@ -896,6 +945,10 @@ void debug_record(keyrecord_t record) #endif } +/** \brief Debug print (FIXME: Needs better description) + * + * FIXME: Needs documentation. + */ void debug_action(action_t action) { switch (action.kind.id) { diff --git a/tmk_core/common/action_code.h b/tmk_core/common/action_code.h index fe2735b97..d836b7a8a 100644 --- a/tmk_core/common/action_code.h +++ b/tmk_core/common/action_code.h @@ -17,10 +17,9 @@ along with this program. If not, see . #ifndef ACTION_CODE_H #define ACTION_CODE_H -/* Action codes - * ============ - * 16bit code: action_kind(4bit) + action_parameter(12bit) +/** \brief Action codes * + * 16bit code: action_kind(4bit) + action_parameter(12bit) * * Key Actions(00xx) * ----------------- @@ -38,7 +37,6 @@ along with this program. If not, see . * 001r|mods|0000 00xx (reserved) * 001r|mods| keycode Modifiers with Tap Key(Dual role) * - * * Other Keys(01xx) * ---------------- * ACT_USAGE(0100): TODO: Not needed? @@ -47,17 +45,14 @@ along with this program. If not, see . * 0100|10| usage(10) (reserved) * 0100|11| usage(10) (reserved) * - * * ACT_MOUSEKEY(0101): TODO: Merge these two actions to conserve space? * 0101|xxxx| keycode Mouse key * * ACT_SWAP_HANDS(0110): * 0110|xxxx| keycode Swap hands (keycode on tap, or options) * - * * 0111|xxxx xxxx xxxx (reserved) * - * * Layer Actions(10xx) * ------------------- * ACT_LAYER(1000): @@ -84,7 +79,6 @@ along with this program. If not, see . * 101E|LLLL|1111 xxxx Reserved (0xF5-FF) * ELLLL: layer 0-31(E: extra bit for layer 16-31) * - * * Extensions(11xx) * ---------------- * ACT_MACRO(1100): @@ -126,7 +120,7 @@ enum action_kind_id { }; -/* Action Code Struct +/** \brief Action Code Struct * * NOTE: * In avr-gcc bit field seems to be assigned from LSB(bit0) to MSB(bit15). @@ -198,10 +192,9 @@ typedef union { #define ACTION(kind, param) ((kind)<<12 | (param)) -/* - * Key Actions - */ -/* Mod bits: 43210 +/** \brief Key Actions + * + * Mod bits: 43210 * bit 0 ||||+- Control * bit 1 |||+-- Shift * bit 2 ||+--- Alt @@ -230,8 +223,7 @@ enum mods_codes { #define ACTION_MODS_TAP_TOGGLE(mods) ACTION(ACT_MODS_TAP, ((mods)&0x1f)<<8 | MODS_TAP_TOGGLE) -/* - * Other Keys +/** \brief Other Keys */ enum usage_pages { PAGE_SYSTEM, @@ -243,20 +235,25 @@ enum usage_pages { -/* - * Layer Actions +/** \brief Layer Actions */ enum layer_param_on { ON_PRESS = 1, ON_RELEASE = 2, ON_BOTH = 3, }; + +/** \brief Layer Actions + */ enum layer_param_bit_op { OP_BIT_AND = 0, OP_BIT_OR = 1, OP_BIT_XOR = 2, OP_BIT_SET = 3, }; + +/** \brief Layer Actions + */ enum layer_param_tap_op { OP_TAP_TOGGLE = 0xF0, OP_ON_OFF, @@ -296,8 +293,7 @@ enum layer_param_tap_op { #define ACTION_DEFAULT_LAYER_BIT_SET(part, bits) ACTION_LAYER_BITOP(OP_BIT_SET, (part), (bits), 0) -/* - * Extensions +/** \brief Extensions */ enum backlight_opt { BACKLIGHT_INCREASE = 0, diff --git a/tmk_core/common/action_layer.c b/tmk_core/common/action_layer.c index 22331376a..f3cd381ab 100644 --- a/tmk_core/common/action_layer.c +++ b/tmk_core/common/action_layer.c @@ -11,16 +11,23 @@ #endif -/* - * Default Layer State +/** \brief Default Layer State */ uint32_t default_layer_state = 0; +/** \brief Default Layer State Set At Keyboard Level + * + * FIXME: Needs docs + */ __attribute__((weak)) uint32_t default_layer_state_set_kb(uint32_t state) { return state; } +/** \brief Default Layer State Set + * + * FIXME: Needs docs + */ static void default_layer_state_set(uint32_t state) { state = default_layer_state_set_kb(state); @@ -31,25 +38,45 @@ static void default_layer_state_set(uint32_t state) clear_keyboard_but_mods(); // To avoid stuck keys } +/** \brief Default Layer Print + * + * FIXME: Needs docs + */ void default_layer_debug(void) { dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state)); } +/** \brief Default Layer Set + * + * FIXME: Needs docs + */ void default_layer_set(uint32_t state) { default_layer_state_set(state); } #ifndef NO_ACTION_LAYER +/** \brief Default Layer Or + * + * FIXME: Needs docs + */ void default_layer_or(uint32_t state) { default_layer_state_set(default_layer_state | state); } +/** \brief Default Layer And + * + * FIXME: Needs docs + */ void default_layer_and(uint32_t state) { default_layer_state_set(default_layer_state & state); } +/** \brief Default Layer Xor + * + * FIXME: Needs docs + */ void default_layer_xor(uint32_t state) { default_layer_state_set(default_layer_state ^ state); @@ -58,21 +85,32 @@ void default_layer_xor(uint32_t state) #ifndef NO_ACTION_LAYER -/* - * Keymap Layer State +/** \brief Keymap Layer State */ uint32_t layer_state = 0; +/** \brief Layer state set user + * + * FIXME: Needs docs + */ __attribute__((weak)) uint32_t layer_state_set_user(uint32_t state) { return state; } +/** \brief Layer state set keyboard + * + * FIXME: Needs docs + */ __attribute__((weak)) uint32_t layer_state_set_kb(uint32_t state) { return layer_state_set_user(state); } +/** \brief Layer state set + * + * FIXME: Needs docs + */ void layer_state_set(uint32_t state) { state = layer_state_set_kb(state); @@ -83,54 +121,98 @@ void layer_state_set(uint32_t state) clear_keyboard_but_mods(); // To avoid stuck keys } +/** \brief Layer clear + * + * FIXME: Needs docs + */ void layer_clear(void) { layer_state_set(0); } +/** \brief Layer state is + * + * FIXME: Needs docs + */ bool layer_state_is(uint8_t layer) { return layer_state_cmp(layer_state, layer); } +/** \brief Layer state compare + * + * FIXME: Needs docs + */ bool layer_state_cmp(uint32_t cmp_layer_state, uint8_t layer) { if (!cmp_layer_state) { return layer == 0; } return (cmp_layer_state & (1UL<. #ifndef NO_ACTION_MACRO #define MACRO_READ() (macro = MACRO_GET(macro_p++)) +/** \brief Action Macro Play + * + * FIXME: Needs doc + */ void action_macro_play(const macro_t *macro_p) { macro_t macro = END; diff --git a/tmk_core/common/action_tapping.c b/tmk_core/common/action_tapping.c index 6280c6c36..8adf013e1 100644 --- a/tmk_core/common/action_tapping.c +++ b/tmk_core/common/action_tapping.c @@ -36,6 +36,10 @@ static void debug_tapping_key(void); static void debug_waiting_buffer(void); +/** \brief Action Tapping Process + * + * FIXME: Needs doc + */ void action_tapping_process(keyrecord_t record) { if (process_tapping(&record)) { @@ -70,7 +74,7 @@ void action_tapping_process(keyrecord_t record) } -/* Tapping +/** \brief Tapping * * Rule: Tap key is typed(pressed and released) within TAPPING_TERM. * (without interfering by typing other key) @@ -289,8 +293,9 @@ bool process_tapping(keyrecord_t *keyp) } -/* - * Waiting buffer +/** \brief Waiting buffer enq + * + * FIXME: Needs docs */ bool waiting_buffer_enq(keyrecord_t record) { @@ -310,12 +315,20 @@ bool waiting_buffer_enq(keyrecord_t record) return true; } +/** \brief Waiting buffer clear + * + * FIXME: Needs docs + */ void waiting_buffer_clear(void) { waiting_buffer_head = 0; waiting_buffer_tail = 0; } +/** \brief Waiting buffer typed + * + * FIXME: Needs docs + */ bool waiting_buffer_typed(keyevent_t event) { for (uint8_t i = waiting_buffer_tail; i != waiting_buffer_head; i = (i + 1) % WAITING_BUFFER_SIZE) { @@ -326,6 +339,10 @@ bool waiting_buffer_typed(keyevent_t event) return false; } +/** \brief Waiting buffer has anykey pressed + * + * FIXME: Needs docs + */ __attribute__((unused)) bool waiting_buffer_has_anykey_pressed(void) { @@ -335,7 +352,10 @@ bool waiting_buffer_has_anykey_pressed(void) return false; } -/* scan buffer for tapping */ +/** \brief Scan buffer for tapping + * + * FIXME: Needs docs + */ void waiting_buffer_scan_tap(void) { // tapping already is settled @@ -359,14 +379,19 @@ void waiting_buffer_scan_tap(void) } -/* - * debug print +/** \brief Tapping key debug print + * + * FIXME: Needs docs */ static void debug_tapping_key(void) { debug("TAPPING_KEY="); debug_record(tapping_key); debug("\n"); } +/** \brief Waiting buffer debug print + * + * FIXME: Needs docs + */ static void debug_waiting_buffer(void) { debug("{ "); diff --git a/tmk_core/common/action_util.c b/tmk_core/common/action_util.c index 148162a51..afd4ae8b2 100644 --- a/tmk_core/common/action_util.c +++ b/tmk_core/common/action_util.c @@ -67,12 +67,12 @@ bool has_oneshot_mods_timed_out(void) { /* oneshot layer */ #ifndef NO_ACTION_ONESHOT -/* oneshot_layer_data bits -* LLLL LSSS -* where: -* L => are layer bits -* S => oneshot state bits -*/ +/** \brief oneshot_layer_data bits + * LLLL LSSS + * where: + * L => are layer bits + * S => oneshot state bits + */ static int8_t oneshot_layer_data = 0; inline uint8_t get_oneshot_layer(void) { return oneshot_layer_data >> 3; } @@ -86,7 +86,10 @@ inline bool has_oneshot_layer_timed_out() { } #endif -/* Oneshot layer */ +/** \brief Set oneshot layer + * + * FIXME: needs doc + */ void set_oneshot_layer(uint8_t layer, uint8_t state) { oneshot_layer_data = layer << 3 | state; @@ -95,12 +98,20 @@ void set_oneshot_layer(uint8_t layer, uint8_t state) oneshot_layer_time = timer_read(); #endif } +/** \brief Reset oneshot layer + * + * FIXME: needs doc + */ void reset_oneshot_layer(void) { oneshot_layer_data = 0; #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0)) oneshot_layer_time = 0; #endif } +/** \brief Clear oneshot layer + * + * FIXME: needs doc + */ void clear_oneshot_layer_state(oneshot_fullfillment_t state) { uint8_t start_state = oneshot_layer_data; @@ -112,12 +123,20 @@ void clear_oneshot_layer_state(oneshot_fullfillment_t state) #endif } } +/** \brief Is oneshot layer active + * + * FIXME: needs doc + */ bool is_oneshot_layer_active(void) { return get_oneshot_layer_state(); } #endif +/** \brief Send keyboard report + * + * FIXME: needs doc + */ void send_keyboard_report(void) { keyboard_report->mods = real_mods; keyboard_report->mods |= weak_mods; @@ -140,29 +159,90 @@ void send_keyboard_report(void) { host_keyboard_send(keyboard_report); } -/* modifier */ +/** \brief Get mods + * + * FIXME: needs doc + */ uint8_t get_mods(void) { return real_mods; } +/** \brief add mods + * + * FIXME: needs doc + */ void add_mods(uint8_t mods) { real_mods |= mods; } +/** \brief del mods + * + * FIXME: needs doc + */ void del_mods(uint8_t mods) { real_mods &= ~mods; } +/** \brief set mods + * + * FIXME: needs doc + */ void set_mods(uint8_t mods) { real_mods = mods; } +/** \brief clear mods + * + * FIXME: needs doc + */ void clear_mods(void) { real_mods = 0; } -/* weak modifier */ +/** \brief get weak mods + * + * FIXME: needs doc + */ uint8_t get_weak_mods(void) { return weak_mods; } +/** \brief add weak mods + * + * FIXME: needs doc + */ void add_weak_mods(uint8_t mods) { weak_mods |= mods; } +/** \brief del weak mods + * + * FIXME: needs doc + */ void del_weak_mods(uint8_t mods) { weak_mods &= ~mods; } +/** \brief set weak mods + * + * FIXME: needs doc + */ void set_weak_mods(uint8_t mods) { weak_mods = mods; } +/** \brief clear weak mods + * + * FIXME: needs doc + */ void clear_weak_mods(void) { weak_mods = 0; } /* macro modifier */ +/** \brief get macro mods + * + * FIXME: needs doc + */ uint8_t get_macro_mods(void) { return macro_mods; } +/** \brief add macro mods + * + * FIXME: needs doc + */ void add_macro_mods(uint8_t mods) { macro_mods |= mods; } +/** \brief del macro mods + * + * FIXME: needs doc + */ void del_macro_mods(uint8_t mods) { macro_mods &= ~mods; } +/** \brief set macro mods + * + * FIXME: needs doc + */ void set_macro_mods(uint8_t mods) { macro_mods = mods; } +/** \brief clear macro mods + * + * FIXME: needs doc + */ void clear_macro_mods(void) { macro_mods = 0; } -/* Oneshot modifier */ #ifndef NO_ACTION_ONESHOT +/** \brief set oneshot mods + * + * FIXME: needs doc + */ void set_oneshot_mods(uint8_t mods) { oneshot_mods = mods; @@ -170,6 +250,10 @@ void set_oneshot_mods(uint8_t mods) oneshot_time = timer_read(); #endif } +/** \brief clear oneshot mods + * + * FIXME: needs doc + */ void clear_oneshot_mods(void) { oneshot_mods = 0; @@ -177,14 +261,19 @@ void clear_oneshot_mods(void) oneshot_time = 0; #endif } +/** \brief get oneshot mods + * + * FIXME: needs doc + */ uint8_t get_oneshot_mods(void) { return oneshot_mods; } #endif -/* - * inspect keyboard state +/** \brief inspect keyboard state + * + * FIXME: needs doc */ uint8_t has_anymod(void) { diff --git a/tmk_core/common/avr/bootloader.c b/tmk_core/common/avr/bootloader.c index ee150817c..d89c8d768 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 dab3eb0f3..0cb774c81 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 213f03f6f..4cdd6a420 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 369015200..b7d4f060e 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) { diff --git a/tmk_core/common/backlight.c b/tmk_core/common/backlight.c index 12f75b38a..3e29aacc4 100644 --- a/tmk_core/common/backlight.c +++ b/tmk_core/common/backlight.c @@ -21,6 +21,10 @@ along with this program. If not, see . backlight_config_t backlight_config; +/** \brief Backlight initialization + * + * FIXME: needs doc + */ void backlight_init(void) { /* check signature */ @@ -34,6 +38,10 @@ void backlight_init(void) backlight_set(backlight_config.enable ? backlight_config.level : 0); } +/** \brief Backlight increase + * + * FIXME: needs doc + */ void backlight_increase(void) { if(backlight_config.level < BACKLIGHT_LEVELS) @@ -46,6 +54,10 @@ void backlight_increase(void) backlight_set(backlight_config.level); } +/** \brief Backlight decrease + * + * FIXME: needs doc + */ void backlight_decrease(void) { if(backlight_config.level > 0) @@ -58,6 +70,10 @@ void backlight_decrease(void) backlight_set(backlight_config.level); } +/** \brief Backlight toggle + * + * FIXME: needs doc + */ void backlight_toggle(void) { backlight_config.enable ^= 1; @@ -68,6 +84,10 @@ void backlight_toggle(void) backlight_set(backlight_config.enable ? backlight_config.level : 0); } +/** \brief Backlight step through levels + * + * FIXME: needs doc + */ void backlight_step(void) { backlight_config.level++; @@ -81,6 +101,10 @@ void backlight_step(void) backlight_set(backlight_config.level); } +/** \brief Backlight set level + * + * FIXME: needs doc + */ void backlight_level(uint8_t level) { if (level > BACKLIGHT_LEVELS) @@ -91,6 +115,10 @@ void backlight_level(uint8_t level) backlight_set(backlight_config.level); } +/** \brief Get backlight level + * + * FIXME: needs doc + */ uint8_t get_backlight_level(void) { return backlight_config.level; diff --git a/tmk_core/common/bootmagic.c b/tmk_core/common/bootmagic.c index 2c6bcbae5..9f79fb8ee 100644 --- a/tmk_core/common/bootmagic.c +++ b/tmk_core/common/bootmagic.c @@ -12,6 +12,10 @@ keymap_config_t keymap_config; +/** \brief Bootmagic + * + * FIXME: needs doc + */ void bootmagic(void) { /* check signature */ @@ -102,6 +106,10 @@ void bootmagic(void) } } +/** \brief Scan Keycode + * + * FIXME: needs doc + */ static bool scan_keycode(uint8_t keycode) { for (uint8_t r = 0; r < MATRIX_ROWS; r++) { @@ -117,9 +125,13 @@ static bool scan_keycode(uint8_t keycode) return false; } +/** \brief Bootmagic Scan Keycode + * + * FIXME: needs doc + */ bool bootmagic_scan_keycode(uint8_t keycode) { if (!scan_keycode(BOOTMAGIC_KEY_SALT)) return false; return scan_keycode(keycode); -} \ No newline at end of file +} diff --git a/tmk_core/common/bootmagic.h b/tmk_core/common/bootmagic.h index 8f6618f4b..f3ea6a24d 100644 --- a/tmk_core/common/bootmagic.h +++ b/tmk_core/common/bootmagic.h @@ -2,6 +2,8 @@ #define BOOTMAGIC_H +/* FIXME: Add special doxygen comments for defines here. */ + /* bootmagic salt key */ #ifndef BOOTMAGIC_KEY_SALT #define BOOTMAGIC_KEY_SALT KC_SPACE diff --git a/tmk_core/common/chibios/bootloader.c b/tmk_core/common/chibios/bootloader.c index 2dd3ade34..f9895237b 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 5ff8ee86f..9061b790c 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 7c3c75387..32ef773e2 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 diff --git a/tmk_core/common/command.h b/tmk_core/common/command.h index a729e4b1e..d9d89ba0f 100644 --- a/tmk_core/common/command.h +++ b/tmk_core/common/command.h @@ -18,6 +18,8 @@ along with this program. If not, see . #ifndef COMMAND_H #define COMMAND +/* FIXME: Add doxygen comments for the behavioral defines in here. */ + /* TODO: Refactoring */ typedef enum { ONESHOT, CONSOLE, MOUSEKEY } command_state_t; extern command_state_t command_state; @@ -154,4 +156,4 @@ bool command_proc(uint8_t code); #define XMAGIC_KC(key) KC_##key #define MAGIC_KC(key) XMAGIC_KC(key) -#endif \ No newline at end of file +#endif diff --git a/tmk_core/common/eeconfig.c b/tmk_core/common/eeconfig.c index e2eb4a38e..91c18e2e6 100644 --- a/tmk_core/common/eeconfig.c +++ b/tmk_core/common/eeconfig.c @@ -3,6 +3,10 @@ #include "eeprom.h" #include "eeconfig.h" +/** \brief eeconfig initialization + * + * FIXME: needs doc + */ void eeconfig_init(void) { eeprom_update_word(EECONFIG_MAGIC, EECONFIG_MAGIC_NUMBER); @@ -24,36 +28,88 @@ void eeconfig_init(void) #endif } +/** \brief eeconfig enable + * + * FIXME: needs doc + */ void eeconfig_enable(void) { eeprom_update_word(EECONFIG_MAGIC, EECONFIG_MAGIC_NUMBER); } +/** \brief eeconfig disable + * + * FIXME: needs doc + */ void eeconfig_disable(void) { eeprom_update_word(EECONFIG_MAGIC, 0xFFFF); } +/** \brief eeconfig is enabled + * + * FIXME: needs doc + */ bool eeconfig_is_enabled(void) { return (eeprom_read_word(EECONFIG_MAGIC) == EECONFIG_MAGIC_NUMBER); } +/** \brief eeconfig read debug + * + * FIXME: needs doc + */ uint8_t eeconfig_read_debug(void) { return eeprom_read_byte(EECONFIG_DEBUG); } +/** \brief eeconfig update debug + * + * FIXME: needs doc + */ void eeconfig_update_debug(uint8_t val) { eeprom_update_byte(EECONFIG_DEBUG, val); } +/** \brief eeconfig read default layer + * + * FIXME: needs doc + */ uint8_t eeconfig_read_default_layer(void) { return eeprom_read_byte(EECONFIG_DEFAULT_LAYER); } +/** \brief eeconfig update default layer + * + * FIXME: needs doc + */ void eeconfig_update_default_layer(uint8_t val) { eeprom_update_byte(EECONFIG_DEFAULT_LAYER, val); } +/** \brief eeconfig read keymap + * + * FIXME: needs doc + */ uint8_t eeconfig_read_keymap(void) { return eeprom_read_byte(EECONFIG_KEYMAP); } +/** \brief eeconfig update keymap + * + * FIXME: needs doc + */ void eeconfig_update_keymap(uint8_t val) { eeprom_update_byte(EECONFIG_KEYMAP, val); } #ifdef BACKLIGHT_ENABLE +/** \brief eeconfig read backlight + * + * FIXME: needs doc + */ uint8_t eeconfig_read_backlight(void) { return eeprom_read_byte(EECONFIG_BACKLIGHT); } +/** \brief eeconfig update backlight + * + * FIXME: needs doc + */ void eeconfig_update_backlight(uint8_t val) { eeprom_update_byte(EECONFIG_BACKLIGHT, val); } #endif #ifdef AUDIO_ENABLE +/** \brief eeconfig read audio + * + * FIXME: needs doc + */ uint8_t eeconfig_read_audio(void) { return eeprom_read_byte(EECONFIG_AUDIO); } +/** \brief eeconfig update audio + * + * FIXME: needs doc + */ void eeconfig_update_audio(uint8_t val) { eeprom_update_byte(EECONFIG_AUDIO, val); } #endif diff --git a/tmk_core/common/keyboard.c b/tmk_core/common/keyboard.c index 001fb00ce..4eff764e2 100644 --- a/tmk_core/common/keyboard.c +++ b/tmk_core/common/keyboard.c @@ -117,19 +117,35 @@ static inline bool has_ghost_in_row(uint8_t row, matrix_row_t rowdata) #endif +/** \brief matrix_setup + * + * FIXME: needs doc + */ __attribute__ ((weak)) void matrix_setup(void) { } +/** \brief keyboard_setup + * + * FIXME: needs doc + */ void keyboard_setup(void) { matrix_setup(); } +/** \brief is_keyboard_master + * + * FIXME: needs doc + */ __attribute__((weak)) bool is_keyboard_master(void) { return true; } +/** \brief keyboard_init + * + * FIXME: needs doc + */ void keyboard_init(void) { timer_init(); matrix_init(); @@ -167,8 +183,16 @@ void keyboard_init(void) { #endif } -/* - * Do keyboard routine jobs: scan matrix, light LEDs, ... +/** \brief Keyboard task: Do keyboard routine jobs + * + * Do routine keyboard jobs: + * + * * scan matrix + * * handle mouse movements + * * run visualizer code + * * handle midi commands + * * light LEDs + * * This is repeatedly called as fast as possible. */ void keyboard_task(void) @@ -274,6 +298,10 @@ MATRIX_LOOP_END: } } +/** \brief keyboard set leds + * + * FIXME: needs doc + */ void keyboard_set_leds(uint8_t leds) { if (debug_keyboard) { debug("keyboard_set_led: "); debug_hex8(leds); debug("\n"); } diff --git a/tmk_core/common/keycode.h b/tmk_core/common/keycode.h index e7e09e098..734c9fbff 100644 --- a/tmk_core/common/keycode.h +++ b/tmk_core/common/keycode.h @@ -22,6 +22,7 @@ along with this program. If not, see . #ifndef KEYCODE_H #define KEYCODE_H +/* FIXME: Add doxygen comments here */ #define IS_ERROR(code) (KC_ROLL_OVER <= (code) && (code) <= KC_UNDEFINED) #define IS_ANY(code) (KC_A <= (code) && (code) <= 0xFF) diff --git a/tmk_core/common/led.h b/tmk_core/common/led.h index 61c971c10..c16305129 100644 --- a/tmk_core/common/led.h +++ b/tmk_core/common/led.h @@ -19,6 +19,7 @@ along with this program. If not, see . #define LED_H #include "stdint.h" +/* FIXME: Add doxygen comments here. */ /* keyboard LEDs */ #define USB_LED_NUM_LOCK 0 @@ -40,4 +41,4 @@ void led_init_ports(void); } #endif -#endif \ No newline at end of file +#endif diff --git a/tmk_core/common/magic.c b/tmk_core/common/magic.c index 49617a3d1..714acc0f5 100644 --- a/tmk_core/common/magic.c +++ b/tmk_core/common/magic.c @@ -14,6 +14,10 @@ keymap_config_t keymap_config; +/** \brief Magic + * + * FIXME: Needs doc + */ void magic(void) { /* check signature */ diff --git a/tmk_core/common/report.c b/tmk_core/common/report.c index 4b25f4428..eb3b44312 100644 --- a/tmk_core/common/report.c +++ b/tmk_core/common/report.c @@ -20,6 +20,10 @@ #include "debug.h" #include "util.h" +/** \brief has_anykey + * + * FIXME: Needs doc + */ uint8_t has_anykey(report_keyboard_t* keyboard_report) { uint8_t cnt = 0; @@ -30,6 +34,10 @@ uint8_t has_anykey(report_keyboard_t* keyboard_report) return cnt; } +/** \brief get_first_key + * + * FIXME: Needs doc + */ uint8_t get_first_key(report_keyboard_t* keyboard_report) { #ifdef NKRO_ENABLE @@ -54,6 +62,10 @@ uint8_t get_first_key(report_keyboard_t* keyboard_report) #endif } +/** \brief add key byte + * + * FIXME: Needs doc + */ void add_key_byte(report_keyboard_t* keyboard_report, uint8_t code) { #ifdef USB_6KRO_ENABLE @@ -120,6 +132,10 @@ void add_key_byte(report_keyboard_t* keyboard_report, uint8_t code) #endif } +/** \brief del key byte + * + * FIXME: Needs doc + */ void del_key_byte(report_keyboard_t* keyboard_report, uint8_t code) { #ifdef USB_6KRO_ENABLE @@ -157,6 +173,10 @@ void del_key_byte(report_keyboard_t* keyboard_report, uint8_t code) } #ifdef NKRO_ENABLE +/** \brief add key bit + * + * FIXME: Needs doc + */ void add_key_bit(report_keyboard_t* keyboard_report, uint8_t code) { if ((code>>3) < KEYBOARD_REPORT_BITS) { @@ -166,6 +186,10 @@ void add_key_bit(report_keyboard_t* keyboard_report, uint8_t code) } } +/** \brief del key bit + * + * FIXME: Needs doc + */ void del_key_bit(report_keyboard_t* keyboard_report, uint8_t code) { if ((code>>3) < KEYBOARD_REPORT_BITS) { @@ -176,6 +200,10 @@ void del_key_bit(report_keyboard_t* keyboard_report, uint8_t code) } #endif +/** \brief add key to report + * + * FIXME: Needs doc + */ void add_key_to_report(report_keyboard_t* keyboard_report, uint8_t key) { #ifdef NKRO_ENABLE @@ -187,6 +215,10 @@ void add_key_to_report(report_keyboard_t* keyboard_report, uint8_t key) add_key_byte(keyboard_report, key); } +/** \brief del key from report + * + * FIXME: Needs doc + */ void del_key_from_report(report_keyboard_t* keyboard_report, uint8_t key) { #ifdef NKRO_ENABLE @@ -198,6 +230,10 @@ void del_key_from_report(report_keyboard_t* keyboard_report, uint8_t key) del_key_byte(keyboard_report, key); } +/** \brief clear key from report + * + * FIXME: Needs doc + */ void clear_keys_from_report(report_keyboard_t* keyboard_report) { // not clear mods diff --git a/tmk_core/protocol/lufa/lufa.c b/tmk_core/protocol/lufa/lufa.c index a1cab98a6..cb918d3dc 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 0df5d3b75..42de80612 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 . 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(); -- cgit v1.2.3-24-g4f1b