diff --git a/sh/document b/sh/document
index 3d83025..dbecbe4 100644
--- a/sh/document
+++ b/sh/document
@@ -8,40 +8,43 @@
 #       https://github.com/dylanaraps/pure-sh-bible
 
 document2() {
-    local f="$1"
-    local c=0
-    local e="${f#sh/}"
+    local f="$1" # file
+    local c=0 # (line) count
+    local e="${f#sh/}" # expecting (function name matches filename)
     [ "$f" != "$e" ] || e=""
-    [ "$e" != document ] || return 0
+    [ "$e" != document ] || return 0 # doesn't play nicely yet, so skip it
     while IFS= read -r line; do
         : $((c+=1))
+        # we only care about lines with our docstring marker on them:
         case "$line" in *'###'*) :;; *) continue;; esac
 
+        # split by the marker:
         local code="${line%%###*}" docs="${line#*###}"
         code="${code#${code%%[![:space:]]*}}" # ltrim
         docs="${docs#${docs%%[![:space:]]*}}" # ltrim
 
-        local s=' ' n=''
+        local s=' ' n='' # using a space to signify unset
 
         case "$docs" in
         @-*)
             s="$code"
-            n="${s%%[!a-zA-Z0-9_-]*}"
+            n="${s%%[!a-zA-Z0-9_-]*}" # substr first word (might not be one)
             while [ -z "$n" -o "$n" = function -o "$n" = alias ]; do
                 [ -n "$s" ] || break
-                s="${s#${s%%[!a-zA-Z0-9_-]*}}"
-                s="${s#*[!a-zA-Z0-9_-]}"
-                n="${s%%[!a-zA-Z0-9_-]*}"
+                s="${s#${s%%[!a-zA-Z0-9_-]*}}" # lstrip to end of word
+                s="${s#*[!a-zA-Z0-9_-]}" # lstrip to next word
+                n="${s%%[!a-zA-Z0-9_-]*}" # substr that word
             done
-            s="${docs#@-}"
+            s="${docs#@-}" # substr the stuff after the hyphen
             s="${s#${s%%[![:space:]]*}}" # ltrim
             ;;
 
         @*-*)
+            # split by the hyphen:
             n="${docs%%-*}"
             s="${docs#*-}"
 
-            n="${n#@}"
+            n="${n#@}" # substr the stuff after the at
             n="${n#${n%%[![:space:]]*}}" # ltrim
             n="${n%${n##*[![:space:]]}}" # rtrim
 
@@ -60,17 +63,21 @@ document2() {
 
         if [ -n "$n" ]; then
             local url
+            # different subdirs need to be handled differently:
             [ "$f" != "${f#sh/}" ] && url="/sh/${f#sh/}#L$c" || url="/home/${f#.}#L$c"
             if [ "$n" = "$e" ]; then
+                # function name matches the filename.
                 printf '\n### [%s](%s)\n\n' "$n" "$url" >> rc/README.md~ || return 5
             else
+                # this file contains some other function, so include the filename.
                 printf '\n### [%s](%s)\n\n' "$n (${f#.})" "$url" >> rc/README.md~ || return 5
                 #printf '\n### %s\n\n* defined in [%s](%s)\n\n' "$n" "$f" "$url" >> rc/README.md~ || return 5
             fi
         fi
 
-        if [ "$s" != ' ' ]; then
-            if [ -z "$n" -o -n "$s" ]; then
+        if [ "$s" != ' ' ]; then # don't bother unless it was set to something
+            if [ -z "$n" -o -n "$s" ]; then # might only be a name, check that
+                # just pass the remaining comment through:
                 printf '%s\n' "$s" >> rc/README.md~ || return 5
             fi
         fi
@@ -81,26 +88,31 @@ document1() {
     # NOTE: in the future, it'd be nice to support arbitary files through arguments.
     [ $# -le 0 ] || return 1
 
+    # sanity check:
     cd || return 2
     [ -d rc ] && [ -d sh ] && [ -f .zshrc ] && [ -f .-shrc ] && [ -f .bashrc ] || return 3
 
+    # create new output file (with a tilde as not to overwrite just yet):
     : > rc/README.md~ || return 4
 
     local line
 
     if [ -f rc/README.md ]; then
+        # copy existing lines up to (and including) the "DOCUMENT" marker:
         while IFS= read -r line; do
             printf '%s\n' "$line" >> rc/README.md~ || return 5
             case "$line" in *DOCUMENT*) break;; esac
         done < rc/README.md || return 4
     fi
 
+    # first section:
     printf '\n## %s\n' 'shell functions' >> rc/README.md~ || return 5
     for f in sh/*; do
-        [ -e "$f" ] || continue
+        [ -e "$f" ] || continue # make sure glob went through
         document2 "$f" || return $?
     done
 
+    # second section:
     printf '\n## %s\n' 'miscellaneous' >> rc/README.md~ || return 5
     document2 .zshrc || return $?
     document2 .bashrc || return $?