Add documentation improvements for v1.1.0 release

Author: mbland

README.md

@@ -342,14 +342,46 @@ your scripts directory. Run `./go help plugins` for more information.
 
 You can import optional Bash library code from the core framework, third-party
 plugins, or your own project's scripts directory by sourcing the
-`$_GO_USE_MODULES` script. For example, to import the core logging utilities:
+`_GO_USE_MODULES` script. For example, to import the core logging utilities:
 
 ```bash
-. $_GO_USE_MODULES 'log'
+. "$_GO_USE_MODULES" 'log'
 ```
 
 Run `./go help modules` and `./go modules --help` for more information.
 
+#### Logging
+
+The core library `log` module provides functions for standard logging
+facilities. For example:
+
+```bash
+@go.log INFO Hello, World!
+@go.log ERROR Goodbye, World!
+```
+
+For more information, run `./go modules --help log`.
+
+#### Bats test assertions and helpers
+
+The assertions and helpers from the test suite have been extracted into the
+`lib/bats/assertions` and `lib/bats/helpers` libraries. While these are not
+modules you can import with `_GO_USE_MODULES`, they are completely independent
+of the rest of the core framework and you may source them in your own Bats
+tests. (Whether or not these will ever become a separate library remains an open
+question.)
+
+Read the comments from each file for more information.
+
+#### `kcov-ubuntu` module for test coverage on Linux
+
+The `kcov-ubuntu` module provides the `run_kcov` function that will download and
+compile [kcov](https://github.com/SimonKagstrom/kcov), then run `kcov` with the
+original `./go` command line arguments to collect test coverage. Only available
+on Ubuntu Linux for now, hence the name. Run `./go modules --help kcov-ubuntu`
+for more information and see `scripts/test` for an example of how it may be
+used.
+
 ### Feedback and contributions
 
 Feel free to [comment on or file a new GitHub

lib/bats/assertions

@@ -24,17 +24,23 @@
 #     fail "output should not match: '$pattern'"
 #   fi
 #
-# Alternatively, write your own assertion functions starting with:
+# Alternatively, write your own assertion function with the following as the
+# first line:
 #
 #   set +o functrace
 #
-# and then make sure every return path calls:
+# and then make sure every return path ends with the following (possibly
+# followed by a `return` statement, if not at the end of the function):
 #
 #   return_from_bats_assertion "$return_status" "$BASH_SOURCE"
 #
 # You may wish to wrap `return_from_bats_assertion` in a local helper function
 # to avoid having to specify `$BASH_SOURCE` everywhere.
 #
+# Also note that if your assertion function calls other assertion functions, you
+# should call `set +o functrace` after every one of them. See the implementation
+# of `assert_lines_equal` for an example.
+#
 # The assertions borrow inspiration from rbenv/test/test_helper.bash.
 
 # Unconditionally returns a failing status

lib/log

@@ -21,7 +21,25 @@
 #   @go.setup_project
 #     Runs the project's 'setup' script and logs the result
 #
-# See the function comments for each of the above for further information.
+# The log level labels are formatted when output to a terminal, and formatting
+# can be forced when writing to a pipe or file by setting `_GO_LOG_FORMATTING`.
+#
+# `@go.log ERROR` will return an error code, so you may use it in conditional
+# statements. `@go.log FATAL` will exit the process.
+#
+# You can pass entire commands to the `@go.log_command` function, which will
+# provide log messages upon startup and completion. Upon error, it will log the
+# status and return an error code, so you may use it in conditional statements.
+# Wrapping blocks of `@go.log_command` invocations in
+# `@go.critical_section_begin` and `@go.critical_section_end` will cause any
+# errors to log `FATAL`. Setting `_GO_DRY_RUN` will log the commands without
+# executing them.
+#
+# The `@go.setup_project` function provides a convenient wrapper for running
+# first-time project setup scripts. It logs the start and finish of the setup
+# script, and provides helpful hints on running the `./go` script upon success.
+#
+# See the function and variable comments from this file for further information.
 
 # Set this if you want to force terminal-formatted output from @go.log.
 #
@@ -229,6 +247,10 @@ declare __GO_CRITICAL_SECTION=0
 # the critical section flag will be shared between parent and child Bash
 # scripts.
 #
+# Globals:
+#   _GO_DRY_RUN:           Will log commands without running them
+#   __GO_CRITICAL_SECTION: Will log FATAL on error
+#
 # Arguments:
 #   $@: The command and its arguments to log and execute
 @go.log_command() {