diff --git a/kyaa.md b/kyaa.md
index b68ae09..dc9dba7 100644
--- a/kyaa.md
+++ b/kyaa.md
@@ -11,6 +11,9 @@ standard library headers:
 * `stdio.h`
 * `string.h`
 
+in addition, `kyaa_extra.h` requires `limits.h`,
+or at least `LONG_MIN` to be defined.
+
 ## tutorial
 
 ensure `argc` and `argv` are defined.
@@ -119,36 +122,39 @@ kyaa prints error messages to `stderr`, and help text to `stdout`.
 
 ### kyaa.h
 
-```
-KYAA_OKAY       DEFINE int
-KYAA_ERROR      DEFINE int
-KYAA_ITER       DEFINE int
-KYAA_SETUP      MACRO
-KYAA_LOOP       MACRO
-KYAA_BEGIN      MACRO
-KYAA_END        MACRO
-KYAA_DESCRIBE   MACRO
-KYAA_FLAG       MACRO
-KYAA_FLAG_ARG   MACRO
-KYAA_HELP       MACRO
-
-kyaa_name           char *
-kyaa_read_stdin     bool
-kyaa_flag           char
-kyaa_keep_parsing   bool
-kyaa_parse_next     bool
-kyaa_arg            char *
-kyaa_no_more        bool
-kyaa_helping        bool
-kyaa_any            bool
-kyaa_flag_arg       char *
-```
+return type or type | name | arguments or default value
+--- | --- | ---
+define          | KYAA\_OKAY            | 0
+define          | KYAA\_ERROR           | 1
+define          | KYAA\_ITER            | i
+||
+macro           | KYAA\_SETUP           | *none*
+macro           | KYAA\_LOOP            | *none*
+macro           | KYAA\_BEGIN           | *none*
+macro           | KYAA\_END             | *none*
+macro           | KYAA\_DESCRIBE        | c, name, description
+macro           | KYAA\_FLAG            | c, name, description
+macro           | KYAA\_FLAG\_ARG       | c, name, description
+macro           | KYAA\_HELP            | description
+||
+`char *`        | kyaa\_name            | *n/a*
+`bool`          | kyaa\_read\_stdin     | *n/a*
+`char *`        | kyaa\_arg             | *n/a*
+|| **internal use** ||
+`char`          | kyaa\_flag            | *n/a*
+`bool`          | kyaa\_keep\_parsing   | *n/a*
+`bool`          | kyaa\_parse\_next     | *n/a*
+`bool`          | kyaa\_no\_more        | *n/a*
+`bool`          | kyaa\_helping         | *n/a*
+`bool`          | kyaa\_any             | *n/a*
 
 ### kyaa\_extra.h
 
-```
-KYAA_FLAG_LONG  MACRO
-
-char        *kyaa_skip_spaces(char *str)
-const char  *kyaa_str_to_long(char *str, long *p_out)
-```
+return value or type | name | arguments or default value
+--- | --- | ---
+macro           | KYAA\_FLAG\_LONG      | c, name, description
+||
+`char *`        | kyaa\_flag\_arg       | *n/a*
+||
+`char *`        | kyaa\_skip\_spaces    | `char *` str
+`const char *`  | kyaa\_str\_to\_long   | `char *` str, `long *` p\_out
diff --git a/kyaa_extra.h b/kyaa_extra.h
index 75dba86..0724326 100644
--- a/kyaa_extra.h
+++ b/kyaa_extra.h
@@ -17,8 +17,7 @@ static char *kyaa_skip_spaces(char *str) {
 static const char *kyaa__base_2(char **p_str, long *p_out) {
     char *str = *p_str;
     long out = *p_out;
-    char c;
-    while ((c = *str++) != '\0') {
+    for (char c; (c = *str) != '\0'; str++) {
         switch (c) {
         case '0': case '1': {
             long digit = (long)(c - '0');
@@ -46,8 +45,7 @@ exit:
 static const char *kyaa__base_8(char **p_str, long *p_out) {
     char *str = *p_str;
     long out = *p_out;
-    char c;
-    while ((c = *str++) != '\0') {
+    for (char c; (c = *str) != '\0'; str++) {
         switch (c) {
         case '0': case '1': case '2': case '3':
         case '4': case '5': case '6': case '7': {
@@ -75,8 +73,7 @@ exit:
 static const char *kyaa__base_10(char **p_str, long *p_out) {
     char *str = *p_str;
     long out = *p_out;
-    char c;
-    while ((c = *str++) != '\0') {
+    for (char c; (c = *str) != '\0'; str++) {
         switch (c) {
         case '0': case '1': case '2': case '3': case '4':
         case '5': case '6': case '7': case '8': case '9': {
@@ -103,8 +100,7 @@ exit:
 static const char *kyaa__base_16(char **p_str, long *p_out) {
     char *str = *p_str;
     long out = *p_out;
-    char c;
-    while ((c = *str++) != '\0') {
+    for (char c; (c = *str) != '\0'; str++) {
         switch (c) {
         case '0': case '1': case '2': case '3': case '4':
         case '5': case '6': case '7': case '8': case '9': {
@@ -177,7 +173,8 @@ static const char *kyaa_str_to_long(char *str, long *p_out) {
 
     if (*str == '\0') return "no number given";
 
-    // TODO: comment on how we go towards negatives instead of positives
+    // NOTE: we actually subtract each digit from the result instead of summing.
+    //       this lets us represent LONG_MIN without overflowing.
     const char *err;
     switch (base) {
         case  2: { err = kyaa__base_2( &str, &out); } break;
@@ -191,6 +188,7 @@ static const char *kyaa_str_to_long(char *str, long *p_out) {
     str = kyaa_skip_spaces(str);
     if (*str != '\0') return "unexpected character";
 
+    // NOTE: out is negative here; see above comment.
     // assuming two's complement
     if (!negated && out == LONG_MIN) return "out of range for long integer";
     *p_out = negated ? out : -out;