From 5fcca9a226b2ab0b1335396e25c37e4b2a261a06 Mon Sep 17 00:00:00 2001
From: Drashna Jaelre <drashna@live.com>
Date: Thu, 17 Jan 2019 09:04:35 -0800
Subject: [PATCH] Add documentation and fix formating (#4860)

---
 tmk_core/common/action_layer.c | 301 ++++++++++++++++-----------------
 1 file changed, 145 insertions(+), 156 deletions(-)

diff --git a/tmk_core/common/action_layer.c b/tmk_core/common/action_layer.c
index 3147d61b36..6ff8c5549b 100644
--- a/tmk_core/common/action_layer.c
+++ b/tmk_core/common/action_layer.c
@@ -17,82 +17,76 @@ uint32_t default_layer_state = 0;
 
 /** \brief Default Layer State Set At user Level
  *
- * FIXME: Needs docs
+ * Run user code on default layer state change
  */
 __attribute__((weak))
 uint32_t default_layer_state_set_user(uint32_t state) {
-    return state;
+  return state;
 }
 
 /** \brief Default Layer State Set At Keyboard Level
  *
- * FIXME: Needs docs
+ *  Run keyboard code on default layer state change
  */
 __attribute__((weak))
 uint32_t default_layer_state_set_kb(uint32_t state) {
-    return default_layer_state_set_user(state);
+  return default_layer_state_set_user(state);
 }
 
 /** \brief Default Layer State Set
  *
- * FIXME: Needs docs
+ * Static function to set the default layer state, prints debug info and clears keys
  */
-static void default_layer_state_set(uint32_t state)
-{
-    state = default_layer_state_set_kb(state);
-    debug("default_layer_state: ");
-    default_layer_debug(); debug(" to ");
-    default_layer_state = state;
-    default_layer_debug(); debug("\n");
+static void default_layer_state_set(uint32_t state) {
+  state = default_layer_state_set_kb(state);
+  debug("default_layer_state: ");
+  default_layer_debug(); debug(" to ");
+  default_layer_state = state;
+  default_layer_debug(); debug("\n");
 #ifdef STRICT_LAYER_RELEASE
-    clear_keyboard_but_mods(); // To avoid stuck keys
+  clear_keyboard_but_mods(); // To avoid stuck keys
 #else
-    clear_keyboard_but_mods_and_keys(); // Don't reset held keys
+  clear_keyboard_but_mods_and_keys(); // Don't reset held keys
 #endif
 }
 
 /** \brief Default Layer Print
  *
- * FIXME: Needs docs
+ * Print out the hex value of the 32-bit default layer state, as well as the value of the highest bit.
  */
-void default_layer_debug(void)
-{
-    dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state));
+void default_layer_debug(void) {
+  dprintf("%08lX(%u)", default_layer_state, biton32(default_layer_state));
 }
 
 /** \brief Default Layer Set
  *
- * FIXME: Needs docs
+ * Sets the default layer state.
  */
-void default_layer_set(uint32_t state)
-{
-    default_layer_state_set(state);
+void default_layer_set(uint32_t state) {
+  default_layer_state_set(state);
 }
 
 #ifndef NO_ACTION_LAYER
 /** \brief Default Layer Or
  *
- * FIXME: Needs docs
+ * Turns on the default layer based on matching bits between specifed layer and existing layer state
  */
-void default_layer_or(uint32_t state)
-{
-    default_layer_state_set(default_layer_state | state);
+void default_layer_or(uint32_t state) {
+  default_layer_state_set(default_layer_state | state);
 }
 /** \brief Default Layer And
  *
- * FIXME: Needs docs
+ * Turns on default layer based on matching enabled bits between specifed layer and existing layer state
  */
-void default_layer_and(uint32_t state)
-{
-    default_layer_state_set(default_layer_state & state);
+void default_layer_and(uint32_t state) {
+  default_layer_state_set(default_layer_state & state);
 }
 /** \brief Default Layer Xor
  *
- * FIXME: Needs docs
+ * Turns on default layer based on non-matching bits between specifed layer and existing layer state
  */
-void default_layer_xor(uint32_t state)
-{
-    default_layer_state_set(default_layer_state ^ state);
+void default_layer_xor(uint32_t state) {
+  default_layer_state_set(default_layer_state ^ state);
 }
 #endif
 
@@ -104,170 +98,168 @@ uint32_t layer_state = 0;
 
 /** \brief Layer state set user
  *
- * FIXME: Needs docs
+ * Runs user code on layer state change
  */
 __attribute__((weak))
 uint32_t layer_state_set_user(uint32_t state) {
-    return state;
+  return state;
 }
 
 /** \brief Layer state set keyboard
  *
- * FIXME: Needs docs
+ * Runs keyboard code on layer state change
  */
 __attribute__((weak))
 uint32_t layer_state_set_kb(uint32_t state) {
-    return layer_state_set_user(state);
+  return layer_state_set_user(state);
 }
 
 /** \brief Layer state set
  *
- * FIXME: Needs docs
+ * Sets the layer to match the specifed state (a bitmask)
  */
-void layer_state_set(uint32_t state)
-{
-    state = layer_state_set_kb(state);
-    dprint("layer_state: ");
-    layer_debug(); dprint(" to ");
-    layer_state = state;
-    layer_debug(); dprintln();
+void layer_state_set(uint32_t state) {
+  state = layer_state_set_kb(state);
+  dprint("layer_state: ");
+  layer_debug(); dprint(" to ");
+  layer_state = state;
+  layer_debug(); dprintln();
 #ifdef STRICT_LAYER_RELEASE
-    clear_keyboard_but_mods(); // To avoid stuck keys
+  clear_keyboard_but_mods(); // To avoid stuck keys
 #else
-    clear_keyboard_but_mods_and_keys(); // Don't reset held keys
+  clear_keyboard_but_mods_and_keys(); // Don't reset held keys
 #endif
 }
 
 /** \brief Layer clear
  *
- * Turn off all layers.
+ * Turn off all layers
  */
-void layer_clear(void)
-{
-    layer_state_set(0);
+void layer_clear(void) {
+  layer_state_set(0);
 }
 
 /** \brief Layer state is
  *
- * Return whether the given state is on (it might still be shadowed by a higher state, though).
+ * Return whether the given state is on (it might still be shadowed by a higher state, though)
  */
-bool layer_state_is(uint8_t layer)
-{
-    return layer_state_cmp(layer_state, layer);
+bool layer_state_is(uint8_t layer) {
+  return layer_state_cmp(layer_state, layer);
 }
 
 /** \brief Layer state compare
  *
- * FIXME: Needs docs
+ * Used for comparing layers {mostly used for unit testing}
  */
 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;
+  if (!cmp_layer_state) { return layer == 0; }
+  return (cmp_layer_state & (1UL<<layer)) != 0;
 }
 
 /** \brief Layer move
  *
- * Turn on the given layer and turn off all other layers.
+ * Turns on the given layer and turn off all other layers
  */
-void layer_move(uint8_t layer)
-{
-    layer_state_set(1UL<<layer);
+void layer_move(uint8_t layer) {
+  layer_state_set(1UL<<layer);
 }
 
 /** \brief Layer on
  *
- * Turn on the given layer.
+ * Turns on given layer
  */
-void layer_on(uint8_t layer)
-{
-    layer_state_set(layer_state | (1UL<<layer));
+void layer_on(uint8_t layer) {
+  layer_state_set(layer_state | (1UL<<layer));
 }
 
 /** \brief Layer off
  *
- * FIXME: Needs docs
+ * Turns off given layer
  */
-void layer_off(uint8_t layer)
-{
-    layer_state_set(layer_state & ~(1UL<<layer));
+void layer_off(uint8_t layer) {
+  layer_state_set(layer_state & ~(1UL<<layer));
 }
 
 /** \brief Layer invert
  *
- * Toggle the given layer (set it if it's unset, or unset it if it's set).
+ * Toggle the given layer (set it if it's unset, or unset it if it's set)
  */
-void layer_invert(uint8_t layer)
-{
-    layer_state_set(layer_state ^ (1UL<<layer));
+void layer_invert(uint8_t layer) {
+  layer_state_set(layer_state ^ (1UL<<layer));
 }
 
 /** \brief Layer or
  *
- * FIXME: Needs docs
+ * Turns on layers based on matching bits between specifed layer and existing layer state
  */
-void layer_or(uint32_t state)
-{
-    layer_state_set(layer_state | state);
+void layer_or(uint32_t state) {
+  layer_state_set(layer_state | state);
 }
 /** \brief Layer and
  *
- * FIXME: Needs docs
+ * Turns on layers based on matching enabled bits between specifed layer and existing layer state
  */
-void layer_and(uint32_t state)
-{
-    layer_state_set(layer_state & state);
+void layer_and(uint32_t state) {
+  layer_state_set(layer_state & state);
 }
 /** \brief Layer xor
  *
- * FIXME: Needs docs
+ * Turns on layers based on non-matching bits between specifed layer and existing layer state
  */
-void layer_xor(uint32_t state)
-{
-    layer_state_set(layer_state ^ state);
+void layer_xor(uint32_t state) {
+  layer_state_set(layer_state ^ state);
 }
 
 /** \brief Layer debug printing
  *
  * Print out the hex value of the 32-bit layer state, as well as the value of the highest bit.
  */
-void layer_debug(void)
-{
-    dprintf("%08lX(%u)", layer_state, biton32(layer_state));
+void layer_debug(void) {
+  dprintf("%08lX(%u)", layer_state, biton32(layer_state));
 }
 #endif
 
 #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
+/** \brief source layer cache
+ */
+
 uint8_t source_layers_cache[(MATRIX_ROWS * MATRIX_COLS + 7) / 8][MAX_LAYER_BITS] = {{0}};
 
-void update_source_layers_cache(keypos_t key, uint8_t layer)
-{
-    const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
-    const uint8_t storage_row = key_number / 8;
-    const uint8_t storage_bit = key_number % 8;
-
-    for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
-        source_layers_cache[storage_row][bit_number] ^=
-            (-((layer & (1U << bit_number)) != 0)
-             ^ source_layers_cache[storage_row][bit_number])
-            & (1U << storage_bit);
-    }
+/** \brief update source layers cache
+ *
+ * Updates the cached keys when changing layers
+ */
+void update_source_layers_cache(keypos_t key, uint8_t layer) {
+  const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
+  const uint8_t storage_row = key_number / 8;
+  const uint8_t storage_bit = key_number % 8;
+
+  for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
+    source_layers_cache[storage_row][bit_number] ^=
+      (-((layer & (1U << bit_number)) != 0)
+        ^ source_layers_cache[storage_row][bit_number])
+      & (1U << storage_bit);
+  }
 }
 
-uint8_t read_source_layers_cache(keypos_t key)
-{
-    const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
-    const uint8_t storage_row = key_number / 8;
-    const uint8_t storage_bit = key_number % 8;
-    uint8_t layer = 0;
-
-    for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
-        layer |=
-            ((source_layers_cache[storage_row][bit_number]
-              & (1U << storage_bit)) != 0)
-            << bit_number;
-    }
-
-    return layer;
+/** \brief read source layers cache
+ *
+ * reads the cached keys stored when the layer was changed
+ */
+uint8_t read_source_layers_cache(keypos_t key) {
+  const uint8_t key_number = key.col + (key.row * MATRIX_COLS);
+  const uint8_t storage_row = key_number / 8;
+  const uint8_t storage_bit = key_number % 8;
+  uint8_t layer = 0;
+
+  for (uint8_t bit_number = 0; bit_number < MAX_LAYER_BITS; bit_number++) {
+    layer |=
+      ((source_layers_cache[storage_row][bit_number]
+        & (1U << storage_bit)) != 0)
+      << bit_number;
+  }
+
+  return layer;
 }
 #endif
 
@@ -278,61 +270,58 @@ uint8_t read_source_layers_cache(keypos_t key)
  * when the layer is switched after the down event but before the up
  * event as they may get stuck otherwise.
  */
-action_t store_or_get_action(bool pressed, keypos_t key)
-{
+action_t store_or_get_action(bool pressed, keypos_t key) {
 #if !defined(NO_ACTION_LAYER) && !defined(STRICT_LAYER_RELEASE)
-    if (disable_action_cache) {
-        return layer_switch_get_action(key);
-    }
-
-    uint8_t layer;
-
-    if (pressed) {
-        layer = layer_switch_get_layer(key);
-        update_source_layers_cache(key, layer);
-    }
-    else {
-        layer = read_source_layers_cache(key);
-    }
-    return action_for_key(layer, key);
-#else
+  if (disable_action_cache) {
     return layer_switch_get_action(key);
+  }
+
+  uint8_t layer;
+
+  if (pressed) {
+    layer = layer_switch_get_layer(key);
+    update_source_layers_cache(key, layer);
+  }
+  else {
+    layer = read_source_layers_cache(key);
+  }
+  return action_for_key(layer, key);
+#else
+  return layer_switch_get_action(key);
 #endif
 }
 
 
 /** \brief Layer switch get layer
  *
- * FIXME: Needs docs
+ * Gets the layer based on key info
  */
-int8_t layer_switch_get_layer(keypos_t key)
-{
+int8_t layer_switch_get_layer(keypos_t key) {
 #ifndef NO_ACTION_LAYER
-    action_t action;
-    action.code = ACTION_TRANSPARENT;
-
-    uint32_t layers = layer_state | default_layer_state;
-    /* check top layer first */
-    for (int8_t i = 31; i >= 0; i--) {
-        if (layers & (1UL<<i)) {
-            action = action_for_key(i, key);
-            if (action.code != ACTION_TRANSPARENT) {
-                return i;
-            }
-        }
+  action_t action;
+  action.code = ACTION_TRANSPARENT;
+
+  uint32_t layers = layer_state | default_layer_state;
+  /* check top layer first */
+  for (int8_t i = 31; i >= 0; i--) {
+    if (layers & (1UL<<i)) {
+      action = action_for_key(i, key);
+      if (action.code != ACTION_TRANSPARENT) {
+          return i;
+      }
     }
-    /* fall back to layer 0 */
-    return 0;
+  }
+  /* fall back to layer 0 */
+  return 0;
 #else
-    return biton32(default_layer_state);
+  return biton32(default_layer_state);
 #endif
 }
 
 /** \brief Layer switch get layer
  *
- * FIXME: Needs docs
+ * Gets action code based on key position
  */
-action_t layer_switch_get_action(keypos_t key)
-{
-    return action_for_key(layer_switch_get_layer(key), key);
+action_t layer_switch_get_action(keypos_t key) {
+  return action_for_key(layer_switch_get_layer(key), key);
 }