Update a bunch of docs

1 files changed, 54 insertions, 74 deletions

diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md
index f01d50416..28927f0ef 100644
--- a/docs/understanding_qmk.md
+++ b/docs/understanding_qmk.md
@@ -1,7 +1,5 @@
 # Understanding QMK's Code
 
-<!-- toc -->
-
 This document attempts to explain how the QMK firmware works from a very high level. It assumes you understand basic programming concepts but does not (except where needed to demonstrate) assume familiarity with C. It assumes that you have a basic understanding of the following documents:
 
 * [QMK Overview](qmk_overview.md)
@@ -12,45 +10,27 @@ This document attempts to explain how the QMK firmware works from a very high le
 
 You can think of QMK as no different from any other computer program. It is started, performs its tasks, and then ends. The entry point for the program is the `main()` function, just like it is on any other C program. However, for a newcomer to QMK it can be confusing because the `main()` function appears in multiple places, and it can be hard to tell which one to look at.
 
-The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios`, `pjrc`, `vusb`, and `bluefruit`, and may support more in the future.
+The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios` and `vusb`.
 
-Let's focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop).
+We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop).
 
 ## The Main Loop
 
-This section of code is called "The Main Loop" because it's responsible for looping over the same set of instructions forever. This is where QMK dispatches out to the functions responsible for making the keyboard do everything it is supposed to. At first glance it can look like a lot of functionality but most of the time the code will be disabled by `#define`'s.
-
-### USB Suspend
-
-```
-    #if !defined(NO_USB_STARTUP_CHECK)
-    while (USB_DeviceState == DEVICE_STATE_Suspended) {
-        print("[s]");
-        suspend_power_down();
-        if (USB_Device_RemoteWakeupEnabled && suspend_wakeup_condition()) {
-                USB_Device_SendRemoteWakeup();
-        }
-    }
-    #endif
-```
-
-This section of code handles the USB suspend state. This state is entered when the computer the keyboard is plugged into is suspended. In this state we don't do anything but wait for the computer we're plugged into to wake up.
-
-### `keyboard_task()`
+This section of code is called "The Main Loop" because it's responsible for looping over the same set of instructions forever. This is where QMK dispatches out to the functions responsible for making the keyboard do everything it is supposed to do. At first glance it can look like a lot of functionality but most of the time the code will be disabled by `#define`'s.
 
 ```
     keyboard_task();
 ```
 
-This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning LED's on and off.
+This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning status LED's on and off.
 
 Within `keyboard_task()` you'll find code to handle:
 
-* Matrix Scanning
+* [Matrix Scanning](#matrix-scanning)
 * Mouse Handling
 * Serial Link(s)
 * Visualizer
-* Keyboard state LED's (Caps Lock, Num Lock, Scroll Lock)
+* Keyboard status LED's (Caps Lock, Num Lock, Scroll Lock)
 
 #### Matrix Scanning
 
@@ -60,18 +40,18 @@ While there are different strategies for doing the actual matrix detection, they
 
 
 ```
-    {
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0}
-    }
+{
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
 ```
 
 That datastructure is a direct representation of the matrix for a 4 row by 5 column numpad. When a key is pressed that key's position within the matrix will be returned as `1` instead of `0`.
 
-Matrix Scanning runs many times per second. The exact rate varies but typically it runs at least 10 times per second to avoid perceptable lag.
+Matrix Scanning runs many times per second. The exact rate varies but typically it runs at least 10 times per second to avoid perceptible lag.
 
 ##### Matrix to Physical Layout Map
 
@@ -114,67 +94,65 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 }
 ```
 
-Notice how all of these arguments match up with the first half of the `KEYMAP()` macro from the last section? This is basically where we take a keycode and map it to our Matrix Scan from earlier. 
+Notice how all of these arguments match up with the first half of the `KEYMAP()` macro from the last section? This is how we take a keycode and map it to our Matrix Scan from earlier. 
 
 ##### State Change Detection
 
 The matrix scanning described above tells us the state of the matrix at a given moment, but your computer only wants to know about changes, it doesn't care about the current state. QMK stores the results from the last matrix scan and compares the results from this matrix to determine when a key has been pressed or released. 
 
-Let's look at an example. We'll hop into the middle of a keyboard scanning look to find that our previous scan looks like this:
+Let's look at an example. We'll hop into the middle of a keyboard scanning loop to find that our previous scan looks like this:
 
 ```
-    {
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0}
-    }
+{
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
 ```
 
 And when our current scan completes it will look like this:
 
 ```
-    {
-        {1,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0},
-        {0,0,0,0}
-    }
+{
+    {1,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
 ```
 
 Comparing against our keymap we can see that the pressed key is KC_NLCK. From here we dispatch to the `process_record` set of functions.
 
-(FIXME: Feels like this section could be fleshed out more.)
-
-(FIXME: Magic happens between here and process_record)
+<!-- FIXME: Magic happens between here and process_record -->
 
 ##### Process Record
 
-The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events looks something like this:
-
-* `void process_record(keyrecord_t *record)`
-  * `bool process_record_quantum(keyrecord_t *record)`
-    * Map this record to a keycode
-    * `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
-      * `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_midi(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_audio(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_music(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_leader(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_chording(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_combo(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_unicode(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_ucis(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_printer(uint16_t keycode, keyrecord_t *record)`
-    * `bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`
-    * Identify and process quantum specific keycodes
-  * Identify and process standard keycodes
+The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is described below, using cluecard whenever we need to look at the keyboard/keymap level functions.
+
+* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L128)
+  * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L140)
+    * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L143)
+    * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/cluecard/cluecard.c#L20)
+      * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/cluecard/keymaps/default/keymap.c#L58)
+    * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_midi.c#L102)
+    * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_audio.c#L10)
+    * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_music.c#L69)
+    * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_tap_dance.c#L75)
+    * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_leader.c#L32)
+    * [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_chording.c#L41)
+    * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_combo.c#L115)
+    * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode.c#L22)
+    * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c#L91)
+    * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_printer.c#L77)
+    * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicodemap.c#L47)
+    * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L211)
   
-At any step during this chain of events a function (such as `process_record_kb()`) can `return false` and processing of that keypress will end immediately.
+At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing.
 
+<!--
 #### Mouse Handling
 
 FIXME: This needs to be written
@@ -190,3 +168,5 @@ FIXME: This needs to be written
 #### Keyboard state LED's (Caps Lock, Num Lock, Scroll Lock)
 
 FIXME: This needs to be written
+
+-->