Add variable docstrings

bin/notifirc

@@ -11,8 +11,8 @@ usage() {
 }
 
 mkcommands() {
-    local user="$1"
-    local nick="$2"
+    local user="$1"     # target user
+    local nick="$2"     # our nickname
     local message
     echo "NICK $nick"
     echo "USER $nick 8 * :notifirc bot"
@@ -31,7 +31,7 @@ mknick() {
 }
 
 die() {
-    local msg="fatal: $1"
+    local msg="fatal: $1"       # message
     log "$msg"
     log "-----END *-----"
     echo "$msg" >&2
@@ -39,13 +39,13 @@ die() {
 }
 
 warn() {
-    local msg="warning: $1"
+    local msg="warning: $1"     # full message
     echo "$msg" >&2
     log "$msg"
 }
 
 log_pipe() {
-    local line
+    local line      # each line of input
     while IFS= read -r line;
     do
         log "$line"
@@ -57,7 +57,7 @@ log() {
 }
 
 load_defaults() {
-    local rcfile=$1
+    local rcfile=$1     # RC file to load
     test -e "$rcfile" || return 0
     test -f "$rcfile" || {
         warn "defaults file is not a file: $rcfile"
@@ -78,10 +78,10 @@ load_defaults() {
 }
 
 trim() {
-    local limit_l=$1
-    local limit_c=$2
-    local lines_read=0
-    local suff=""
+    local limit_l=$1        # max. lines per message
+    local limit_c=$2        # max. chars per line
+    local lines_read=0      # how many lines we read
+    local suff=""           # suffix (ellipsis)
     while true;
     do
         test $lines_read -ge "$limit_l" && break
@@ -94,7 +94,7 @@ trim() {
 }
 
 choose_logfile() {
-    local path
+    local path      # path to log file
     {
         echo /var/log/notifirc.log
         echo "$HOME/.notifirc.log"
@@ -112,8 +112,16 @@ choose_logfile() {
 }
 
 main() {
-    local context nick host port user message logfile msgfile
-    local f_maxlines=3 f_maxwidth=80
+    local context           # context tag for nickname
+    local nick              # bot's nickname
+    local host              # IRC server hostname
+    local port              # ... ^^ ... port
+    local user              # user to notify
+    local message           # message to send
+    local logfile           # logfile to use
+    local msgfile           # file to read message from
+    local f_maxlines=3      # maximum number of lines per notification
+    local f_maxwidth=80     # maximum characters per notification line
 
     logfile=$(choose_logfile)
     test -n "$logfile" || {