Add a bit of docs to key_events.h

Briefly document the key event handling flow, to make it clearer how the
functions can be used.

Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>

src/key_events.h

@@ -15,8 +15,36 @@ extern uint8_t temporary_keymap;
 extern const Key keymaps[][ROWS][COLS];
 
 // sending events to the computer
-void handle_synthetic_key_event( Key mappedKey, uint8_t currentState, uint8_t previousState);
+/* The event handling starts with the Scanner calling handle_key_event() for
+ * every key in the matrix, and it is the task of this method to figure out what
+ * to do, it is the main entry point.
+ *
+ * This function will iterate through an array of handler functions, and stop as
+ * soon as one of them signals that the event has been handled. To make it
+ * possible to inject synthetic events, one can call handle_key_event from
+ * within a custom handler (making the event handling recursive), with a
+ * different keycode.
+ *
+ * This is useful for example for one-shot modifiers, where we would like to
+ * temporarily disable the one-shot functionality, and have them work as a
+ * normal modifier instead. In this case, the keymap would contain a key with
+ * OSM flags set, and the event handler would remove the OSM flags, and let the
+ * system handle the key as it would have, without the OSM flags. So we simply
+ * clear the flags, and call handle_key_event again, with the modifier keycode
+ * as the first argument. This way, we could insert an event, and have the whole
+ * chain re-process it, instead of registering the keycode ourselves with HID
+ * ourselves. Injecting allows any and all custom handlers to have a chance,
+ * too.
+ *
+ * For this reason, the handle_key_event receives four arguments: the mapped key
+ * (or Key_NoKey if we do not want to override what is in the keymap), the row
+ * and column of the key, so we can look up the code for it, and the current and
+ * previous state of the key, so we can determine what the event is.
+ */
 void handle_key_event(Key mappedKey, byte row, byte col, uint8_t currentState, uint8_t previousState);
+
+// Internal use
+void handle_synthetic_key_event( Key mappedKey, uint8_t currentState, uint8_t previousState);
 void press_key(Key mappedKey);
 void handle_keymap_key_event(Key keymapEntry, uint8_t currentState, uint8_t previousState);
 void handle_mouse_key_event(Key mappedKey, uint8_t currentState, uint8_t previousState);