Add function docstrings

bin/notifirc

@@ -2,6 +2,9 @@
 
 
 usage() {
+    #
+    # Print usage message and exit with status 2
+    #
     local self      # our name
     self=$(basename "$0")
     echo "usage: $self [options] message" >&2
@@ -11,6 +14,9 @@ usage() {
 }
 
 mkcommands() {
+    #
+    # Print all IRC commands
+    #
     local user="$1"     # target user
     local nick="$2"     # our nickname
     local message
@@ -24,6 +30,9 @@ mkcommands() {
 }
 
 mknick() {
+    #
+    # Compose bot's nickname
+    #
     case "$context" in
         "") echo "$nick" ;;
         *)  echo "$nick|$context" ;;
@@ -31,6 +40,9 @@ mknick() {
 }
 
 die() {
+    #
+    # End script with fatal error $1
+    #
     local msg="fatal: $1"       # message
     log "$msg"
     log "-----END *-----"
@@ -39,12 +51,18 @@ die() {
 }
 
 warn() {
+    #
+    # Issue message $1 as warning to logfile and stderr
+    #
     local msg="warning: $1"     # full message
     echo "$msg" >&2
     log "$msg"
 }
 
 log_pipe() {
+    #
+    # Log contents of standard input
+    #
     local line      # each line of input
     while IFS= read -r line;
     do
@@ -53,10 +71,16 @@ log_pipe() {
 }
 
 log() {
+    #
+    # Log message $1 to $logfile
+    #
     echo "$1" >>"$logfile"
 }
 
 load_defaults() {
+    #
+    # Load defaults from RC file $1
+    #
     local rcfile=$1     # RC file to load
     test -e "$rcfile" || return 0
     test -f "$rcfile" || {
@@ -78,6 +102,9 @@ load_defaults() {
 }
 
 trim() {
+    #
+    # Trim to maximum $1 lines and $2 characters per line
+    #
     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
@@ -94,6 +121,9 @@ trim() {
 }
 
 choose_logfile() {
+    #
+    # Decide which log file to use (/var, /home or /tmp)
+    #
     local path      # path to log file
     {
         echo /var/log/notifirc.log