Document print_log_message function

lib/core_lib.sh

@@ -179,6 +179,32 @@ make_temp_file () {
 # Computes and prepends a timestamp to the LOG_MESSAGE
 # before appending the message to a log file.
 #
+# Options:
+#   -T  enable TRACE logging
+#   -D  enable DEBUG logging
+#   -I  enable INFO logging (default)
+#   -W  enable WARN logging
+#   -E  enable ERROR logging
+#   -F  enable FATAL logging
+#
+# The command-line options are mutually exclusive. If no option is
+# given on the command line, the -I option is assumed.
+#
+# Two environment variables are consulted:
+#
+#   LOG_FILE:  Path to the log file (REQUIRED)
+#   LOG_LEVEL: Global log level [0..5] (OPTIONAL)
+#
+# If LOG_FILE is not set or the file is not found, the script
+# immediately terminates. If LOG_LEVEL is not set, the value 
+# LOG_LEVEL=3 is used by default.
+#
+# The command-line options interact with the global log level.
+# A message may or may not be logged depending on the chosen 
+# option in relation to the global log level. Specifically, if
+# the log level indicated on the command line is greater than
+# the global log level, the log operation is short-circuited.
+#
 # This script is compatible with Mac OS and GNU/Linux.
 #######################################################################