Update and fix docstrings

src/saturnin.sh.skel

@@ -199,8 +199,29 @@ saturnin__conf_find() {
     #
     # Find all existing instances of sub-path $1 on $SATURNIN_CONF_PATH
     #
-    # Go through all elements of $SATURNIN_CONF_PATH, looking for file on
-    # sub-path $1.  Print each existing path, ignore rest.
+    # Usage:
+    #
+    #     saturnin__conf_find SUBPATH
+    #
+    # Go through all elements of $SATURNIN_CONF_PATH, looking for file or
+    # directory, whose path is formed by joining SUBPATH to element of
+    # $SATURNIN_CONF_PATH.  Print each existing path, ignore rest.
+    #
+    # For example, with following setup:
+    #
+    #     SATURNIN_CONF_PATH=foo:bar:baz
+    #     mkdir -p foo/one bar/one
+    #     mkdir -p bar/two/slashes
+    #
+    # call
+    #
+    #     saturnin__conf_find one
+    #
+    # would print `foo/one` and `bar/one`, while
+    #
+    #     saturnin__conf_find two/slashes
+    #
+    # would print `bar/two/slashes`.
     #
     # If at least one path was found, return zero.  Otherwise, return one,
     # or more in case of error.
@@ -380,10 +401,10 @@ saturnin__runhook() {
 
 saturnin__runsc() {
     #
-    # Run subcommand $SATURNIN_SUBCOMMAND
+    # Run subcommand $1 with arguments $2..
     #
-    local subcommand="$1"; shift
-    local binpath   # path to subcommand's binary
+    local subcommand="$1"; shift    # subcommand to run
+    local binpath                   # path to subcommand's binary
     binpath+="$SATURNIN_LIBEXEC/"
     binpath+="$SATURNIN_LIBEXEC_PREFIX$subcommand"
     debug -v binpath
@@ -412,7 +433,11 @@ saturnin__usage() {
 
 saturnin__version() {
     #
-    # Print version info
+    # Print human-readable version info
+    #
+    # Basic version info is already stored in $SATURNIN_APP_VERSION,
+    # this function prints more descriptive paragraph including Saturnin's
+    # own version.
     #
     echo -n "$(basename "$0")"
     test -n "$SATURNIN_APP_TAGLINE" \
@@ -436,7 +461,7 @@ saturnin__wraphook() {
     # status of the payload command, even if hooks fail.  Ignore post-hook
     # if payload command failed.
     #
-    local es=0      # exit status of thid function
+    local es=0      # exit status of this function
     saturnin__runhook pre
     "$@" || return $?
     es=$?
@@ -463,8 +488,8 @@ _saturnin__conf__merge() {
     #
     # Take paths and applying merge strategy, load file(s)
     #
-    local path
-    local found=false
+    local path          # every path
+    local found=false   # 'true' if we got any path
     while read -r path;
     do
         found=true
@@ -496,8 +521,8 @@ _saturnin__conf__load() {
     # 'first' strategy, first existing file is printed, with 'join'
     # strategy, all existing files are printed.
     #
-    local arg es
-    es=0
+    local arg       # each passed argument
+    local es=0      # exit status of this function
     for arg in "$@";
     do
         case $arg in
@@ -515,7 +540,7 @@ _saturnin__conf__load() {
 
 _saturnin__conf_usage() {
     #
-    # Show usage message and exit
+    # Show usage message, passing $@ to mkusage() and exit
     #
     PRETTY_USAGE="self=${0##*/} conf" \
     mkusage "$@"                                                              \