Add hook document from njbair's work

tmk/tmk_keyboard#323

Author: tmk

doc/hook.txt

@@ -0,0 +1,112 @@
+Hooks
+-----
+Hooks allow you to execute custom code at certain predefined points in the firmware execution. To use them, just define the hook function in your keymap file.
+
+The following hooks are available available:
+
+Hook function | Called in file | Timing
+---|---|---
+`hook_keyboard_start(void)` | *protocol/\<protocol>.c* | Early in the boot process, before the matrix is initialized and before a connection is made with the host. Thus, this hook has access to very few parameters, but it is a good place to define any custom parameters needed by other early processes.
+`hook_keyboard_init(void)` | *protocol/\<protocol>.c* | Near the end of the boot process, after Boot Magic has run and LEDs have been initialized.
+`hook_bootmagic(void)` | *common/bootmagic.c* | During the Boot Magic window, after EEPROM and Bootloader checks are made, but before any other built-in Boot Magic checks are made.
+`hook_usb_suspend(void)` | *protocol/\<protocol>.c* | When the device enters USB suspend state. *Default action:* enable LED breathing.
+`hook_usb_wakeup(void)` | *protocol/\<protocol>.c* | When the device wakes up from USB suspend state. *Default action:* disable LED breathing.
+`hook_suspend_loop(void)` | *protocol/\<protocol>.c* | Continuously, while the device is in USB suspend state. *Default action:* power down and periodically check the matrix, causing wakeup if needed.
+`hook_keyboard_loop(void)` | *common/keyboard.c* | Continuously, during the main loop, after the matrix is checked. Note that the protocol and interrupt configuration may affect the timing. If you need precise timing, use one of the `hook_interval_*` functions listed below.
+`hook_matrix_change(keyevent_t event)` | *common/action.c* | When a keypress event is detected, before any other actions are processed.
+`hook_layer_state_change(uint32_t layer_state)` | *common/action_layer.c* | When any layer is turned on or off. `layer_state` is a 32-bit integer containing the 0/1 state of all 32 layers, one bit per layer (see [keymap documentation](tmk_core/doc/keymap.md)).
+`hook_default_layer_state_change(uint32_t default_layer_state)` | *common/action_layer.c* | When the default layer is changed. `default_layer_state` is a 32-bit integer with a single bit set to 1 indicating the default layer (see [keymap documentation](tmk_core/doc/keymap.md)).
+`hook_leds_change(uint8_t led_status)` | *common/keyboard.c* | Whenever a change in the LED status is performed. *Default action:* call `keyboard_set_leds(led_status)`
+
+### Hooks Examples
+
+You can try these out by copying the code to your keymap file, or any .c file in the Makefile `SRC`.
+
+#### Activate keymap layer 5 on startup
+
+```C
+#include "action_layer.h"
+
+void hook_keyboard_init(void)
+{
+    layer_on(5);
+    print("Layer 5 enabled!");
+}
+```
+
+#### Blink the Caps Lock LED every .5 seconds
+
+```C
+#include "timer.h"
+#include "led.h"
+
+bool my_led_status = 0;
+uint16_t my_led_timer;
+
+void hook_keyboard_loop(void)
+{
+    // check if we've reached 500 milliseconds yet...
+    if (timer_elapsed(my_led_timer) > 500)
+    {
+        // we've reached 500 milliseconds!
+        // reset the timer
+        my_led_timer = timer_read();
+
+        // check the current LED state
+        if (my_led_status)
+        {
+            // LED is on, so let's turn it off
+            led_set(host_keyboard_leds() & (0<<USB_LED_CAPS_LOCK));
+            my_led_status = 0;
+        }
+        else
+        {
+            // LED is off, so let's turn it on
+            led_set(host_keyboard_leds() | (1<<USB_LED_CAPS_LOCK));
+            my_led_status = 1;
+        }
+    }
+}
+```
+
+#### Flash the Caps Lock LED for 20ms on every keypress
+```C
+#include "timer.h"
+#include "led.h"
+
+bool my_led_status = 0;
+uint16_t my_led_timer;
+
+void hook_matrix_change(keyevent_t event)
+{
+    // only flash LED for key press events, not key release events.
+    if (event.pressed)
+    {
+        // check the current LED status and reverse it
+        if (host_keyboard_leds() & (1<<USB_LED_CAPS_LOCK))
+        {
+            led_set(host_keyboard_leds() & (0<<USB_LED_CAPS_LOCK));
+        }
+        else {
+            led_set(host_keyboard_leds() | (1<<USB_LED_CAPS_LOCK));
+        }
+
+        my_led_status = 1;
+        my_led_timer = timer_read();
+    }
+}
+
+void hook_keyboard_loop(void)
+{
+    if (my_led_status)
+    {
+        // check if we've reached 20 milliseconds yet...
+        if (timer_elapsed(my_led_timer) > 20)
+        {
+            keyboard_set_leds(host_keyboard_leds());
+
+            my_led_status = 0;
+        }
+    }
+}
+```