all.sh: Update the maintainer documentation
diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index 1d92c80..e03efe8 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -55,21 +55,46 @@
# Notes for maintainers
# ---------------------
#
+# The bulk of the code is organized into functions that follow one of the
+# following naming conventions:
+# * pre_XXX: things to do before running the tests, in order.
+# * component_XXX: independent components. They can be run in any order.
+# * component_check_XXX: quick tests that aren't worth parallelizing.
+# * component_build_XXX: build things but don't run them.
+# * component_test_XXX: build and test.
+# * support_XXX: if support_XXX exists and returns false then
+# component_XXX is not run by default.
+# * post_XXX: things to do after running the tests.
+# * other: miscellaneous support functions.
+#
+# Each component must start by invoking `msg` with a short informative message.
+#
+# The framework performs some cleanup tasks after each component. This
+# means that components can assume that the working directory is in a
+# cleaned-up state, and don't need to perform the cleanup themselves.
+# * Run `make clean`.
+# * Restore `include/mbedtks/config.h` from a backup made before running
+# the component.
+# * Check out `Makefile`, `library/Makefile`, `programs/Makefile` and
+# `tests/Makefile` from git. This cleans up after an in-tree use of
+# CMake.
+#
+# Any command that is expected to fail must be protected so that the
+# script keeps running in --keep-going mode despite `set -e`. In keep-going
+# mode, if a protected command fails, this is logged as a failure and the
+# script will exit with a failure status once it has run all components.
+# Commands can be protected in any of the following ways:
+# * `make` is a function which runs the `make` command with protection.
+# Note that you must write `make VAR=value`, not `VAR=value make`,
+# because the `VAR=value make` syntax doesn't work with functions.
+# * Put `report_status` before the command to protect it.
+# * Put `if_build_successful` before a command. This protects it, and
+# additionally skips it if a prior invocation of `make` in the same
+# component failed.
+#
# The tests are roughly in order from fastest to slowest. This doesn't
# have to be exact, but in general you should add slower tests towards
# the end and fast checks near the beginning.
-#
-# Sanity checks have the following form:
-# 1. msg "short description of what is about to be done"
-# 2. run sanity check (failure stops the script)
-#
-# Build or build-and-test steps have the following form:
-# 1. msg "short description of what is about to be done"
-# 2. cleanup
-# 3. preparation (config.pl, cmake, ...) (failure stops the script)
-# 4. make
-# 5. Run tests if relevant. All tests must be prefixed with
-# if_build_successful for the sake of --keep-going.