document run_multiple_progs

diff --git a/t/test.pl b/t/test.pl
index c5d2845..e8c5605 100644 (file)
--- a/t/test.pl
+++ b/t/test.pl
@@ -876,6 +876,33 @@ sub fresh_perl_like {
 # Many tests use the same format in __DATA__ or external files to specify a
 # sequence of (fresh) tests to run, extra files they may temporarily need, and
 # what the expected output is. So have excatly one copy of the code to run that
+#
+# Each program is source code to run followed by an "EXPECT" line, followed
+# by the expected output.
+#
+# The code to run may contain:
+#   # TODO reason for todo
+#   # SKIP reason for skip
+#   # SKIP ?code to test if this should be skipped
+#   # NAME name of the test (as with ok($ok, $name))
+#
+# The expected output may contain:
+#   OPTION list of options
+#   OPTIONS list of options
+#   PREFIX
+#     indicates that the supplied output is only a prefix to the
+#     expected output
+#
+# The possible options for OPTION may be:
+#   regex - the expected output is a regular expression
+#   random - all lines match but in any order
+#   fatal - the code will fail fatally (croak, die)
+#
+# If the actual output contains a line "SKIPPED" the test will be
+# skipped.
+#
+# If the global variable $FATAL is true then OPTION fatal is the
+# default.
 
 sub run_multiple_progs {
     my $up = shift;