diff --git a/firmware/keyboard/ergodox/layout/common/definitions.h b/firmware/keyboard/ergodox/layout/common/definitions.h
index 7f50b2e..65bddcb 100644
--- a/firmware/keyboard/ergodox/layout/common/definitions.h
+++ b/firmware/keyboard/ergodox/layout/common/definitions.h
@@ -69,7 +69,7 @@ void KF(transp) (void) {}
 #define  keys__press__transp    KF(transp)
 #define  keys__release__transp  KF(transp)
 
-/**                                                        keys/nop/desctiption
+/**                                                        keys/nop/description
  * no operation
  *
  * This key does nothing (and is not transparent).
diff --git a/firmware/lib/eeprom.h b/firmware/lib/eeprom.h
index d3781b1..87cc5ff 100644
--- a/firmware/lib/eeprom.h
+++ b/firmware/lib/eeprom.h
@@ -148,9 +148,8 @@ uint8_t eeprom__block_read (void * to, void * from, uint8_t length);
  * - If `to > from`, copying should start with the given addresses, and
  *   decrement for `length - 1` bytes
  *
- * - Undefined behavior will result if any address in either the block you're
- *   copying from (`from`..`from+length-1`) or the block you're copying to
- *   (`to`..`to+length-1`) is invalid.
+ * - Undefined behavior will result if any address in the block of EEMEM you're
+ *   copying from or the block of EEMEM you're copying to is invalid.
  */
 
 // === eeprom__block_read() ===
@@ -170,13 +169,14 @@ uint8_t eeprom__block_read (void * to, void * from, uint8_t length);
  * Notes:
  * - As one would expect, this read is performed sequentially, and all data is
  *   read in before returning.  Delays due to the speed of the EEPROM are
- *   introduced *for every byte* whether one uses this function or
+ *   introduced *for every byte* whether one uses this function or reads each
+ *   byte manually.
  * - Because doing a "block_write" would be either unbearably slow or require
  *   us to work around the fact that the function would return before the data
- *   was actually written (so where would the data to be written stored? we'd
- *   either have to copy it, or make an agreement with the calling functions to
- *   `malloc()` the data and let us `free()` it, or some such), we do not have
- *   any "block" functions that write to the EEPROM (except perhaps
+ *   was actually written (so where would the data to be written be stored?
+ *   we'd either have to copy it, or make an agreement with the calling
+ *   functions to `malloc()` the data and let us `free()` it, or some such), we
+ *   do not have any "block" functions that write to the EEPROM (except perhaps
  *   `eeprom__fill()`, which is a special case).  Better to be careful with
  *   writes, and schedule them one at a time, using `eeprom__write()`.
  */
diff --git a/firmware/lib/layout/eeprom-macro/atmega32u4.c b/firmware/lib/layout/eeprom-macro/atmega32u4.c
index 797e062..84c7913 100644
--- a/firmware/lib/layout/eeprom-macro/atmega32u4.c
+++ b/firmware/lib/layout/eeprom-macro/atmega32u4.c
@@ -51,7 +51,7 @@
     #error "OPT__EEPROM__EEPROM_MACRO__END must not be greater than 1023"
 #endif
 
-#if EEMEM_END - EEMEM_START < 300
+#if OPT__EEPROM__EEPROM_MACRO__END - OPT__EEPROM__EEPROM_MACRO__START < 300
     #warn "Only a small space has been allocated for macros"
 #endif
 
@@ -185,14 +185,14 @@
  *   of the EEPROM have the same values for each.
  */
 #define  EEMEM_START                ((void *)OPT__EEPROM__EEPROM_MACRO__START)
-#define  EEMEM_START_ADDRESS_START  EEMEM_START               + 0
-#define  EEMEM_START_ADDRESS_END    EEMEM_START_ADDRESS_START + 1
-#define  EEMEM_END_ADDRESS_START    EEMEM_START_ADDRESS_END + 1
-#define  EEMEM_END_ADDRESS_END      EEMEM_END_ADDRESS_START + 1
-#define  EEMEM_VERSION_START        EEMEM_END_ADDRESS_END + 1
-#define  EEMEM_VERSION_END          EEMEM_VERSION_START   + 0
-#define  EEMEM_MACROS_START         EEMEM_VERSION_END + 1
-#define  EEMEM_MACROS_END           EEMEM_END         - 0
+#define  EEMEM_START_ADDRESS_START  (EEMEM_START               + 0)
+#define  EEMEM_START_ADDRESS_END    (EEMEM_START_ADDRESS_START + 1)
+#define  EEMEM_END_ADDRESS_START    (EEMEM_START_ADDRESS_END + 1)
+#define  EEMEM_END_ADDRESS_END      (EEMEM_END_ADDRESS_START + 1)
+#define  EEMEM_VERSION_START        (EEMEM_END_ADDRESS_END + 1)
+#define  EEMEM_VERSION_END          (EEMEM_VERSION_START   + 0)
+#define  EEMEM_MACROS_START         (EEMEM_VERSION_END + 1)
+#define  EEMEM_MACROS_END           (EEMEM_END         - 0)
 #define  EEMEM_END                  ((void *)OPT__EEPROM__EEPROM_MACRO__END)
 
 /**                                             macros/(group) type/description
@@ -320,7 +320,7 @@ key_action_t read_key_action(void ** from) {
 uint8_t write_key_action(void ** to, key_action_t k) {
 
     // - we need to leave room after this macro (and therefore after this
-    //   key-action) for the `TYPE_END` byte
+    //   key-action) for the `type == TYPE_END` byte
     if ((*to) > EEMEM_END-4)
         return 1;  // error: might not be enough space
 
@@ -372,13 +372,31 @@ uint8_t write_key_action(void ** to, key_action_t k) {
 // ----------------------------------------------------------------------------
 // TODO:
 //
-// - the calling function need not ignore layer shift keys, or any other keys.
+// - i was thinking before that the calling function need not ignore layer
+//   shift keys, or any other keys.  now i think that layer keys (or at least
+//   layer shift keys) really should be ignored.  not doing so may lead to all
+//   sorts of fun problems.  for example, if the "begin/end recording" key is
+//   not on layer 0 (which it probably won't be), the last keys pressed (but
+//   not released) will most likely be layer shift keys -- but since these keys
+//   were not released before we stopped recording, there would be no record of
+//   their release, and the macro would therefore push that layer onto the
+//   layer stack, and never pop it off.
 //
 // - 255 bytes (so, on average, about 100 keystrokes = 200 key actions) should
 //   be enough for a macro, i think.  `length` can be 1 byte, and count the
 //   total number of bytes (including `type` and `length`, and anything else)
 //
-// - need to write `kb__layout__exec_key_layer()` (or something)
+// - need to write something like:
+//     - `kb__layout__exec_key_layer()`
+//         - `kb__layout__exec_key()` could just look up the current layer
+//           (falling through for transparent keys), and then call
+//           `kb__layout__exec_key_layer()`.  this would obviate the need for a
+//           separate `static get_layer(void)` function, since the
+//           functionality would essentially be separated out anyway.
+//     - `kb__led__delay__error()`
+//         - "delay" because it should probably flash a few times, or
+//           something, and i feel like it'd be better overall to not continue
+//           accepting input while that's happening.
 //
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
diff --git a/firmware/lib/layout/key-functions/special.c b/firmware/lib/layout/key-functions/special.c
index 3fcca81..dd930b5 100644
--- a/firmware/lib/layout/key-functions/special.c
+++ b/firmware/lib/layout/key-functions/special.c
@@ -11,7 +11,7 @@
 
 #include <stdbool.h>
 #include <stdint.h>
-#include <avr/pgmspace.h>
+#include <avr/pgmspace.h>  // for `key_functions__type_string()`
 #include "../../../../firmware/lib/usb.h"
 #include "../../../../firmware/lib/usb/usage-page/keyboard.h"
 #include "../key-functions.h"
diff --git a/firmware/main.c b/firmware/main.c
index 0c4f1dc..8ffd458 100644
--- a/firmware/main.c
+++ b/firmware/main.c
@@ -28,10 +28,6 @@
  *
  * Notes:
  * - Cherry MX bounce time <= 5ms (at 16 in/sec actuation speed) (spec)
- *
- * TODO: does this documentation (and preprocessor check) belong in "main.h"?
- * also, does the note belong in the keyboard "options.h", as an
- * "implementation note"?
  */
 #ifndef OPT__DEBOUNCE_TIME
     #error "OPT__DEBOUNCE_TIME not defined"