Improve documentation

bashutils.sh

@@ -26,6 +26,9 @@
 
 
 # Environment control
+## => Restores the environment
+## => Arguments: none
+## => Returns: 0
 function _bashutils_restore_environment() {
   if [ -n "${_BASHUTILS_ENVIRONMENT_PREVIOUS_OPTIONS}" ]; then
     [[ "${_BASHUTILS_ENVIRONMENT_PREVIOUS_OPTIONS}" == *"e"* ]] && set -e
@@ -38,7 +41,14 @@ function _bashutils_restore_environment() {
     [ -z "${_BASHUTILS_ENVIRONMENT_PREVIOUS_PIPEFAIL}" ] && set +o pipefail
     unset _BASHUTILS_ENVIRONMENT_PREVIOUS_OPTIONS
   fi
+
+  return 0
 }
+## => Resets the environment to optimal conditions for bashutils
+## => Arguments:
+##    -> 1. none
+##    -> 2. [?...:command to execute]
+## => Returns: 0 or the command's exit code if one is supplied
 function _bashutils_reset_environment() {
   export "_BASHUTILS_ENVIRONMENT_PREVIOUS_OPTIONS=${-}"
   [ -o "pipefail" ] && export "_BASHUTILS_ENVIRONMENT_PREVIOUS_PIPEFAIL=true"
@@ -53,7 +63,14 @@ function _bashutils_reset_environment() {
     _bashutils_restore_environment
     return "${EXITCODE}"
   fi
+
+  return 0
 }
+## => Resets the environment and returns the first argument.
+##    This is useful in situations where the environment shall
+##    be reset and the exit code preserved.
+## => Arguments: <byte:exit code>
+## => Returns: the provided exit code
 function _bashutils_return_environment() {
   _bashutils_restore_environment
   return "${1:-0}"
@@ -61,12 +78,33 @@ function _bashutils_return_environment() {
 
 
 # Logging
+## => Prints a diagnostic message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function diag() { [ "${BASHUTILS_LOGLEVEL}" -lt 1 ] && echo -e "DIAG  ${*//\\n/\\n      }"; }
+## => Prints a verbose message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function verb() { [ "${BASHUTILS_LOGLEVEL}" -lt 2 ] && echo -e "VERB  ${*//\\n/\\n      }"; }
+## => Prints a silent warning message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function sarn() { [ "${BASHUTILS_LOGLEVEL}" -lt 3 ] && echo -e "SARN  ${*//\\n/\\n      }"; }
+## => Prints an informational message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function info() { [ "${BASHUTILS_LOGLEVEL}" -lt 4 ] && echo -e "INFO  ${*//\\n/\\n      }"; }
+## => Prints a warning message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function warn() { [ "${BASHUTILS_LOGLEVEL}" -lt 5 ] && echo -e "WARN  ${*//\\n/\\n      }"; }
+## => Prints an error message.
+## => Arguments: <str...:message>
+## => Returns: 0
 function error() { [ "${BASHUTILS_LOGLEVEL}" -lt 6 ] && echo -e "ERR!  ${*//\\n/\\n      }" &> /dev/stderr; }
+## => Handles crashes.
+## => Arguments: <bool:terminate?> <str...:message>
+## => Returns: 0
 function crash() {
   _bashutils_reset_environment
   [ "${1}" == "true" ] && CRASH_TERMINATE=true || CRASH_TERMINATE=false
@@ -101,15 +139,40 @@ EOF
 }
 
 # Checks
+## Command type
+## => Checks whether the provided command name is an alias.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_alias() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == alias ]]; _bashutils_return_environment ${?}; }
+## => Checks whether the provided command name is a keyword.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_keyword() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == keyword ]]; _bashutils_return_environment ${?}; }
+## => Checks whether the provided command name is a function.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_function() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == function ]]; _bashutils_return_environment ${?}; }
+## => Checks whether the provided command name is a builtin.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_builtin() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == builtin ]]; _bashutils_return_environment ${?}; }
+## => Checks whether the provided command name is a file.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_file() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == file ]]; _bashutils_return_environment ${?}; }
+## => Checks whether the provided command name is defined.
+## => Arguments: <str:command name>
+## => Returns: 0 if it is, 1 otherwise
 function is_command_defined() { _bashutils_reset_environment; [[ "$(type -t "${1}")" == "" ]]; _bashutils_return_environment ${?}; }
 
 # Variable definition
+## => Sets the specified variable to the specified value if it is undefined.
+## => Arguments: <str:variable> <?:value>
+## => Returns: 0 if it is, 1 otherwise
 function set_undefined() { _bashutils_reset_environment; [ -z "${!1}" ] && export "${1}=${2}"; _bashutils_restore_environment; }
+## => Sets the specified variable to the specified value if it is defined.
+## => Arguments: <str:variable> <?:value>
+## => Returns: 0 if it is, 1 otherwise
 function set_defined() { _bashutils_reset_environment; [ -n "${!1}" ] && export "${1}=${2}"; _bashutils_restore_environment; }
 
 

docs/docs/features/checks.md

@@ -24,8 +24,8 @@ is_command_builtin "echo" && echo "'echo'" is built into bash"
 ! is_command_defined "setup" && echo "ERROR: 'setup' is undefined"
 ```
 
-## Command type checks
+## Command type
-These check the type of the passed command and return `0` if it matches or `1` if it doesn't.
+These checks check the type of the passed command and return `0` if it matches or `1` if it doesn't.
 
 <table>
  <tr> 

docs/docs/features/logging.md

@@ -22,32 +22,32 @@ required arguments along.
  <tr>   
   <td>Diagnostic</td>
   <td>0</td>
-  <td><code>diag &lt;str:message&gt;</code></td>
+  <td><code>diag &lt;str...:message&gt;</code></td>
  </tr>
  <tr>   
   <td>Verbose</td>
   <td>1</td>
-  <td><code>verb &lt;str:message&gt;</code></td>
+  <td><code>verb &lt;str..:message&gt;</code></td>
  </tr>
  <tr>   
   <td>Silent warning</td>
   <td>2</td>
-  <td><code>sarn &lt;str:message&gt;</code></td>
+  <td><code>sarn &lt;str...:message&gt;</code></td>
  </tr>
  <tr>   
   <td>Informational</td>
   <td>3</td>
-  <td><code>info &lt;str:message&gt;</code></td>
+  <td><code>info &lt;str...:message&gt;</code></td>
  </tr>
  <tr>   
   <td>Warning</td>
   <td>4</td>
-  <td><code>warn &lt;str:message&gt;</code></td>
+  <td><code>warn &lt;str...:message&gt;</code></td>
  </tr>
  <tr>   
   <td>Error</td>
   <td>5</td>
-  <td><code>error &lt;str:message&gt;</code></td>
+  <td><code>error &lt;str...:message&gt;</code></td>
  </tr>
 </table>
 
@@ -56,7 +56,7 @@ bashutils includes a fully functional crash handler.
 It prints information about the operating system, environment, stack trace and of course the crash itself.
 And, if you wish, it will terminate the script with code `69`.
 
-To trigger a crash, simply invoke `crash <bool:terminate> <str:message>`.
+To trigger a crash, simply invoke `crash <bool:terminate> <str...:message>`.
 
 ## Customization
 bashutils allows you to customize the logging system via environment variables.

docs/docs/introduction/datatypes.md

@@ -7,6 +7,9 @@ description: Describes which data types bashutils uses and understands.
 # Data types
 This document describes which data types bashutils can understand.
 
+## `?`
+Denotes a lack of data types. This means any data type is accepted.
+
 ## `bool`
 Booleans. May only be `true` or `false`. `1` or `0` is not supported and will be treated as a number instead.