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

25 files changed, 732 insertions, 70 deletions

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 <fauxclicky.h>
 #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 <http://www.gnu.org/licenses/>.
 #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 <http://www.gnu.org/licenses/>.
  * 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 <http://www.gnu.org/licenses/>.
  * 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 <http://www.gnu.org/licenses/>.
  * 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<<layer)) != 0;
 }
 
+/** \brief Layer move
+ *
+ * FIXME: Needs docs
+ */
 void layer_move(uint8_t layer)
 {
     layer_state_set(1UL<<layer);
 }
 
+/** \brief Layer on
+ *
+ * FIXME: Needs docs
+ */
 void layer_on(uint8_t layer)
 {
     layer_state_set(layer_state | (1UL<<layer));
 }
 
+/** \brief Layer off
+ *
+ * FIXME: Needs docs
+ */
 void layer_off(uint8_t layer)
 {
     layer_state_set(layer_state & ~(1UL<<layer));
 }
 
+/** \brief Layer invert
+ *
+ * FIXME: Needs docs
+ */
 void layer_invert(uint8_t layer)
 {
     layer_state_set(layer_state ^ (1UL<<layer));
 }
 
+/** \brief Layer or
+ *
+ * FIXME: Needs docs
+ */
 void layer_or(uint32_t state)
 {
     layer_state_set(layer_state | state);
 }
+/** \brief Layer and
+ *
+ * FIXME: Needs docs
+ */
 void layer_and(uint32_t state)
 {
     layer_state_set(layer_state & state);
 }
+/** \brief Layer xor
+ *
+ * FIXME: Needs docs
+ */
 void layer_xor(uint32_t state)
 {
     layer_state_set(layer_state ^ state);
 }
 
+/** \brief Layer debug printing
+ *
+ * FIXME: Needs docs
+ */
 void layer_debug(void)
 {
     dprintf("%08lX(%u)", layer_state, biton32(layer_state));
@@ -172,7 +254,8 @@ uint8_t read_source_layers_cache(keypos_t key)
 }
 #endif
 
-/*
+/** \brief Store or get action (FIXME: Needs better summary)
+ *
  * Make sure the action triggered when the key is released is the same
  * one as the one triggered on press. It's important for the mod keys
  * when the layer is switched after the down event but before the up
@@ -201,6 +284,10 @@ action_t store_or_get_action(bool pressed, keypos_t key)
 }
 
 
+/** \brief Layer switch get layer
+ *
+ * FIXME: Needs docs
+ */
 int8_t layer_switch_get_layer(keypos_t key)
 {
 #ifndef NO_ACTION_LAYER
@@ -224,6 +311,10 @@ int8_t layer_switch_get_layer(keypos_t key)
 #endif
 }
 
+/** \brief Layer switch get layer
+ *
+ * FIXME: Needs docs
+ */
 action_t layer_switch_get_action(keypos_t key)
 {
     return action_for_key(layer_switch_get_layer(key), key);
diff --git a/tmk_core/common/action_macro.c b/tmk_core/common/action_macro.c
index 7726b1190..12bef2958 100644
--- a/tmk_core/common/action_macro.c
+++ b/tmk_core/common/action_macro.c
@@ -29,6 +29,10 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #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 <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
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 <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)
 {
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 <http://www.gnu.org/licenses/>.
 
 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 <http://www.gnu.org/licenses/>.
 #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 <http://www.gnu.org/licenses/>.
 #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 <http://www.gnu.org/licenses/>.
 #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 <http://www.gnu.org/licenses/>.
 
 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();