Add shellfu() docstring

src/shellfu.sh.skel

@@ -35,17 +35,17 @@ SHELLFU_EMBEDDED=${SHELLFU_EMBEDDED:-false}
 SHELLFU_GIT_HASH=__MKIT_PROJ_GIT_LASTHASH__
 
 #
-# Includes folder prefix
+# Module folder prefix
 #
-# Modules are searched for in path formed by this prefix, plus
-# 'sh', plus run-time value of SHELLFU_COMPAT, and if set, in
-# directories listed in SHELLFU_PATH
+# See shellfu() documentation for details about module loading.
 #
 SHELLFU_INCLUDE=${SHELLFU_INCLUDE:-$SHELLFU_DIR/include}
 
 #
 # Colon separated list of additional paths to search modules
 #
+# See shellfu() documentation for details about module loading.
+#
 SHELLFU_PATH=${SHELLFU_PATH:-}
 
 #
@@ -59,6 +59,59 @@ SHELLFU_VERSION=__MKIT_PROJ_VERSION__
 __SHELLFU_IMPORTED=${__SHELLFU_IMPORTED:-}
 
 shellfu() {
+    #
+    # Shellfu init function
+    #
+    # Usage:
+    #
+    #     shellfu ACTION MODULE
+    #
+    # MODULE is selected and acted upon, depending on ACTION:
+    #
+    #  * `import` will source the module using shell built-in dot command.
+    #
+    #  * `try_import` will try to import the module in a separate environment
+    #     and exit with zero on success (it will not modity the current
+    #     environment).
+    #
+    #  *  `version` will look for directive `#shellfu module-version: VER`
+    #     and print the VER part.
+    #
+    # The module lookup algorithm triest to find file MODULE.sh in following
+    # directories:
+    #
+    #  1. Any directories in colon-separated list SHELLFU_PATH,
+    #
+    #  2. directory formed by joining SHELLFU_INCLUDE and SHELLFU_COMPAT
+    #     with dingle dash,
+    #
+    #  3. directory formed by joining 'sh' and SHELLFU_COMPAT with single
+    #     dash.
+    #
+    # for example, following code:
+    #
+    #     #!/bin/bash
+    #
+    #     . $(sfpath)
+    #
+    #     SHELLFU_INCLUDE=/shellfu/include
+    #     SHELLFU_PATH=/shellfu/addon1:/shellfu/addon2
+    #
+    #     shellfu import foo
+    #
+    # will import first existing file of these:
+    #
+    #     /shellfu/addon1/foo.sh
+    #     /shellfu/addon2/foo.sh
+    #     /shellfu/include-bash/foo.sh
+    #     /shellfu/include-sh/foo.sh
+    #
+    # Note that SHELLFU_COMPAT should be auto-detected by shellfu and should
+    # contain name of current shell binary being executed.  This means that
+    # modules can exist in multiple versions for each supported shell, and
+    # when loading, shellfu prefers the shell-specific implementation.
+    #
+
     local cmd=$1; shift
     local msg