Move globals/io/exit to top

This helps keep the IO and exit status details near usage.
It also will help with parsing as we generate man pages from this data.

9 files changed, 86 insertions, 88 deletions

diff --git a/src/assert.bash b/src/assert.bash
index 5197b76..0260ce2 100644
--- a/src/assert.bash
+++ b/src/assert.bash
@@ -4,13 +4,21 @@
 # Summary: Fail if the given expression evaluates to false.
 #
 # Usage: assert <expression>
-#
+
 # Options:
 #   <expression>    The expression to evaluate for truthiness.
 #                   *__Note:__ The expression must be a simple command.
 #                   [Compound commands](https://www.gnu.org/software/bash/manual/bash.html#Compound-Commands),
 #                   such as `[[`, can be used only when executed with `bash -c`.*
 #
+# IO:
+#   STDERR - the failed expression, on failure
+# Globals:
+#   none
+# Returns:
+#   0 - if expression evaluates to true
+#   1 - otherwise
+#
 #   ```bash
 #   @test 'assert()' {
 #     touch '/var/log/test.log'
@@ -25,14 +33,6 @@
 #   expression : [ -e /var/log/test.log ]
 #   --
 #   ```
-#
-# Globals:
-#   none
-# Returns:
-#   0 - if expression evaluates to true
-#   1 - otherwise
-# Outputs:
-#   STDERR - the failed expression, on failure
 assert() {
   if ! "$@"; then
     batslib_print_kv_single 10 'expression' "$*" \
diff --git a/src/assert_equal.bash b/src/assert_equal.bash
index 5c1d674..4ef1297 100644
--- a/src/assert_equal.bash
+++ b/src/assert_equal.bash
@@ -15,6 +15,14 @@
 #   }
 #   ```
 #
+# IO:
+#   STDERR - expected and actual values, on failure
+# Globals:
+#   none
+# Returns:
+#   0 - if values equal
+#   1 - otherwise
+#
 # On failure, the expected and actual values are displayed.
 #
 #   ```
@@ -23,14 +31,6 @@
 #   actual   : have
 #   --
 #   ```
-#
-# Globals:
-#   none
-# Returns:
-#   0 - if values equal
-#   1 - otherwise
-# Outputs:
-#   STDERR - expected and actual values, on failure
 assert_equal() {
   if [[ $1 != "$2" ]]; then
     batslib_print_kv_single_or_multi 8 \
diff --git a/src/assert_failure.bash b/src/assert_failure.bash
index dcd3393..5567f73 100644
--- a/src/assert_failure.bash
+++ b/src/assert_failure.bash
@@ -9,6 +9,17 @@
 #   <expected_status>    The specific status code to check against.
 #                        If not provided, simply asserts status is != 0.
 #
+# IO:
+#   STDERR - `$output`, on failure;
+#          - also, `$status` and `expected_status`, if provided
+# Globals:
+#   status
+#   output
+# Returns:
+#   0 - if `$status' is 0,
+#       or if expected_status is provided but does not equal `$status'
+#   1 - otherwise
+#
 #   ```bash
 #   @test 'assert_failure() status only' {
 #     run echo 'Success!'
@@ -44,17 +55,6 @@
 #   output   : Error!
 #   --
 #   ```
-#
-# Globals:
-#   status
-#   output
-# Returns:
-#   0 - if `$status' is 0,
-#       or if expected_status is provided but does not equal `$status'
-#   1 - otherwise
-# Outputs:
-#   STDERR - `$output`, on failure;
-#          - also, `$status` and `expected_status`, if provided
 assert_failure() {
   : "${output?}"
   : "${status?}"
diff --git a/src/assert_line.bash b/src/assert_line.bash
index 8ce4844..35d8492 100644
--- a/src/assert_line.bash
+++ b/src/assert_line.bash
@@ -11,6 +11,16 @@
 #   -e, --regexp      Treat `expected` as an extended regular expression
 #   <expected>        The expected line string, substring, or regular expression
 #
+# IO:
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   output
+#   lines
+# Returns:
+#   0 - if matching line found
+#   1 - otherwise
+#
 # Similarly to `assert_output`, this function verifies that a command or function produces the expected output.
 # (Logical complement of `refute_line`)
 # It checks that the expected line appears in the output (default) or at a specific line number.
@@ -116,16 +126,6 @@
 #   line   : have-1
 #   --
 #   ```
-#
-# Globals:
-#   output
-#   lines
-# Returns:
-#   0 - if matching line found
-#   1 - otherwise
-# Outputs:
-#   STDERR - details, on failure
-#            error message, on error
 # FIXME(ztombol): Display `${lines[@]}' instead of `$output'!
 assert_line() {
   local -i is_match_line=0
diff --git a/src/assert_output.bash b/src/assert_output.bash
index 314efa1..a5c9fb1 100644
--- a/src/assert_output.bash
+++ b/src/assert_output.bash
@@ -11,11 +11,21 @@
 #   -, --stdin     Read `expected` value from STDIN
 #   <expected>     The expected value, substring or regular expression
 #
+# IO:
+#   STDIN - [=$1] expected output
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   output
+# Returns:
+#   0 - if output matches the expected value/partial/regexp
+#   1 - otherwise
+#
 # This function verifies that a command or function produces the expected output.
 # (Logical complement of `refute_output`)
 # Output matching can be literal (the default), partial or by regular expression.
 # The expected output can be specified either by positional argument or from STDIN by passing `-`/`--stdin` flag.
-
+#
 # #### Literal matching
 #
 # By default, literal matching is performed.
@@ -111,17 +121,6 @@
 #   output : Foobar 0.1.0
 #   --
 #   ```
-#
-# Globals:
-#   output
-# Returns:
-#   0 - if output matches the expected value/partial/regexp
-#   1 - otherwise
-# Inputs:
-#   STDIN - [=$1] expected output
-# Outputs:
-#   STDERR - details, on failure
-#            error message, on error
 assert_output() {
   local -i is_mode_partial=0
   local -i is_mode_regexp=0
diff --git a/src/assert_success.bash b/src/assert_success.bash
index a180048..a8b2a38 100644
--- a/src/assert_success.bash
+++ b/src/assert_success.bash
@@ -5,6 +5,15 @@
 #
 # Usage: assert_success
 #
+# IO:
+#   STDERR - `$status` and `$output`, on failure
+# Globals:
+#   status
+#   output
+# Returns:
+#   0 - if `$status' is 0
+#   1 - otherwise
+#
 #   ```bash
 #   @test 'assert_success() status only' {
 #     run bash -c "echo 'Error!'; exit 1"
@@ -20,15 +29,6 @@
 #   output : Error!
 #   --
 #   ```
-#
-# Globals:
-#   status
-#   output
-# Returns:
-#   0 - if `$status' is 0
-#   1 - otherwise
-# Outputs:
-#   STDERR - `$status` and `$output`, on failure
 assert_success() {
   : "${output?}"
   : "${status?}"
diff --git a/src/refute.bash b/src/refute.bash
index a9b6f94..e7c47da 100644
--- a/src/refute.bash
+++ b/src/refute.bash
@@ -11,6 +11,14 @@
 #                   [Compound commands](https://www.gnu.org/software/bash/manual/bash.html#Compound-Commands),
 #                   such as `[[`, can be used only when executed with `bash -c`.*
 #
+# IO:
+#   STDERR - the successful expression, on failure
+# Globals:
+#   none
+# Returns:
+#   0 - if expression evaluates to false
+#   1 - otherwise
+#
 #   ```bash
 #   @test 'refute()' {
 #     rm -f '/var/log/test.log'
@@ -25,14 +33,6 @@
 #   expression : [ -e /var/log/test.log ]
 #   --
 #   ```
-#
-# Globals:
-#   none
-# Returns:
-#   0 - if expression evaluates to false
-#   1 - otherwise
-# Outputs:
-#   STDERR - the successful expression, on failure
 refute() {
   if "$@"; then
     batslib_print_kv_single 10 'expression' "$*" \
diff --git a/src/refute_line.bash b/src/refute_line.bash
index c3badf6..7868416 100644
--- a/src/refute_line.bash
+++ b/src/refute_line.bash
@@ -11,6 +11,16 @@
 #   -e, --regexp      Treat `unexpected` as an extended regular expression
 #   <unexpected>      The unexpected line string, substring, or regular expression.
 #
+# IO:
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   output
+#   lines
+# Returns:
+#   0 - if match not found
+#   1 - otherwise
+#
 # Similarly to `refute_output`, this function verifies that a command or function does not produce the unexpected output.
 # (Logical complement of `assert_line`)
 # It checks that the unexpected line does not appear in the output (default) or at a specific line number.
@@ -119,16 +129,6 @@
 #   line   : Foobar v0.1.0
 #   --
 #   ```
-#
-# Globals:
-#   output
-#   lines
-# Returns:
-#   0 - if match not found
-#   1 - otherwise
-# Outputs:
-#   STDERR - details, on failure
-#            error message, on error
 # FIXME(ztombol): Display `${lines[@]}' instead of `$output'!
 refute_line() {
   local -i is_match_line=0
diff --git a/src/refute_output.bash b/src/refute_output.bash
index 1e89abc..c0156ed 100644
--- a/src/refute_output.bash
+++ b/src/refute_output.bash
@@ -11,6 +11,16 @@
 #   -, --stdin     Read `unexpected` value from STDIN
 #   <unexpected>   The unexpected value, substring, or regular expression
 #
+# IO:
+#   STDIN - [=$1] unexpected output
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   output
+# Returns:
+#   0 - if output matches the unexpected value/partial/regexp
+#   1 - otherwise
+#
 # This function verifies that a command or function does not produce the unexpected output.
 # (Logical complement of `assert_output`)
 # Output matching can be literal (the default), partial or by regular expression.
@@ -111,17 +121,6 @@
 #   output : Foobar v0.1.0
 #   --
 #   ```
-#
-# Globals:
-#   output
-# Returns:
-#   0 - if output matches the unexpected value/partial/regexp
-#   1 - otherwise
-# Inputs:
-#   STDIN - [=$1] unexpected output
-# Outputs:
-#   STDERR - details, on failure
-#            error message, on error
 refute_output() {
   local -i is_mode_partial=0
   local -i is_mode_regexp=0