documentation; and minor LED functionality in main()

firmware/keyboard.h

@@ -5,10 +5,9 @@
  * ------------------------------------------------------------------------- */
 
 /**                                                                 description
- * The keyboard interface, and related definitions.
+ * The keyboard interface
  *
- * Keyboard implementations must conditionally define their dimensions in this
- * file, and implement all prototyped functions.
+ * Keyboard implementations must implement all prototyped functions.
  *
  * Prefix: `kb__`
  */

firmware/lib/data-types/list.h

@@ -14,9 +14,9 @@
  * Usage notes:
  *
  * - All functions that accept an `index` set `index %= list->length` before
- *   using it.  This will make all passed indices valid.  It will also provide
- *   a convenient way to reference the last element of a list, by passing `-1`
- *   as the index (as in Python).
+ *   using it.  This will make all passed indices valid.  It also provides a
+ *   convenient way to reference the last element of a list, by passing `-1` as
+ *   the index (as in Python).
  *
  * - All pointers to `list__node_t` are stored, returned, etc. as as `void`
  *   pointers until use, so that using files won't have to do so much work
@@ -50,8 +50,8 @@
  *
  * Assumptions:
  *
- * - Lists will never contain more elements than can be indexed by an `int8_t`
- *   (i.e. 128)
+ * - Lists will never contain more than 128 elements (the number of elements
+ *   that can be indexed by an `int8_t`).
  */
 
 
@@ -186,6 +186,7 @@ void           list__free          (list__list_t * list);
  *
  * Returns:
  * - success: A `void *` pointer to `node`
+ * - failure: `NULL`
  */
 
 // === list__pop_node_next() ===
@@ -200,6 +201,12 @@ void           list__free          (list__list_t * list);
  * Returns:
  * - success: A `void *` pointer to the next node in the list
  * - failure: `NULL`
+ *
+ * Notes:
+ * - This is helpful, sometimes, when iterating through a list, some of who's
+ *   members need to be removed.  If performance is critical, keep in mind that
+ *   it does have the O(n) time penalty of having to re-search the list for the
+ *   given node's predecesor before removing the node.
  */
 
 // === list__free() ===

firmware/lib/data-types/list/list.c

@@ -15,7 +15,8 @@
 
 // ----------------------------------------------------------------------------
 
-#define  N(name)  ((list__node_t *)name)  // cast to `list__node_t *`
+// since we'll be casting to type `list__node_t *` a lot
+#define  N(name)  ((list__node_t *)name)
 
 // ----------------------------------------------------------------------------
 
@@ -153,9 +154,12 @@ void * list__pop_node(list__list_t * list, void * node) {
 }
 
 void * list__pop_node_next(list__list_t * list, void * node) {
-    list__pop_node(list, node);
+    if (!list__pop_node(list, node))
+        return NULL;
+
     void * next = N(node)->next;
     free(node);
+
     return next;
 }
 

firmware/lib/timer.h

@@ -142,6 +142,6 @@ uint8_t  timer__schedule         ( uint16_t milliseconds,
  * - If a function needs a longer wait time than is possible with a 16-bit
  *   millisecond resolution counter, it can repeatedly schedule itself to run
  *   in, say, 1 minute, increment a counter each time, and then only execute
- *   its body code after, say 5 calls (for a 5 minute delay).
+ *   its body code after, say, 5 calls (for a 5 minute delay).
  */
 

firmware/lib/timer/atmega32u4.md

@@ -57,11 +57,11 @@
     --------------------------------------------
      prescale value       ticks per millisecond
     ----------------     -----------------------
-     1                    16000
-     8                     2000
-     64                     250
-     256                     62.5
-     1024                    15.625
+                  1       16000
+                  8        2000
+                 64         250
+                256          62.5
+               1024          15.625
     --------------------------------------------
 
     * So if we set the prescaler to 64, we can just barely get to a millisecond

firmware/main.c

@@ -37,6 +37,7 @@
 #define  main__was_pressed  was_pressed
 #define  main__row          row
 #define  main__col          col
+#define  main__update_leds  update_leds
 
 // ----------------------------------------------------------------------------
 
@@ -47,9 +48,12 @@ static bool _pressed_2[OPT__KB__ROWS][OPT__KB__COLUMNS];
 
 bool (* is_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS] = &_pressed_1;
 bool (* was_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS] = &_pressed_2;
+
 uint8_t row;
 uint8_t col;
 
+bool update_leds = true;
+
 // --- for `main__timer__` functions ---
 
 typedef struct {
@@ -124,17 +128,19 @@ int main(void) {
 
         // note: only use the `kb__led__logical...` functions here, since the
         // meaning of the physical LEDs should be controlled by the layout
-        #define  read  usb__kb__read_led
-        #define  on    kb__led__logical_on
-        #define  off   kb__led__logical_off
-        read('N') ? on('N') : off('N');  // numlock
-        read('C') ? on('C') : off('C');  // capslock
-        read('S') ? on('S') : off('S');  // scroll lock
-        read('O') ? on('O') : off('O');  // compose
-        read('K') ? on('K') : off('K');  // kana
-        #undef read
-        #undef on
-        #undef off
+        if (update_leds) {
+            #define  read  usb__kb__read_led
+            #define  on    kb__led__logical_on
+            #define  off   kb__led__logical_off
+            read('N') ? on('N') : off('N');  // numlock
+            read('C') ? on('C') : off('C');  // capslock
+            read('S') ? on('S') : off('S');  // scroll lock
+            read('O') ? on('O') : off('O');  // compose
+            read('K') ? on('K') : off('K');  // kana
+            #undef read
+            #undef on
+            #undef off
+        }
 
         // take care of `main__timer__` stuff
         _cycles++;

firmware/main.h

@@ -42,6 +42,8 @@ extern bool (* main__was_pressed) [OPT__KB__ROWS][OPT__KB__COLUMNS];
 extern uint8_t main__row;
 extern uint8_t main__col;
 
+extern bool main__update_leds;
+
 // ----------------------------------------------------------------------------
 
 uint8_t  main__timer__init     (void);
@@ -86,6 +88,18 @@ uint8_t  main__timer__schedule (uint16_t cycles, void(*function)(void));
  * Indicates which column is currently being tested for changes of key state
  */
 
+// === main__update_leds ===
+/**                                     variables/main__update_leds/description
+ * A predicate indicating whether to update the keyboard LED state based on the
+ * USB LED state
+ *
+ * This is for taking over control the LEDs temporarily, as one may want to
+ * do when in a special mode, etc.  If you want to change the meaning of the
+ * LEDs under normal use, the correct place to do that is in the layout file,
+ * where the `kb__led__logical_*()` functions are defined (see the
+ * documentation in that and related files for more information).
+ */
+
 
 // ----------------------------------------------------------------------------
 // functions ------------------------------------------------------------------