[6791] test_utils.pl comments

[Gavin D. Smith]

Revision: 6791
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6791
Author:   gavin
Date:     2015-11-21 14:57:34 +0000 (Sat, 21 Nov 2015)
Log Message:
-----------
test_utils.pl comments

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/tp/t/README
    trunk/tp/t/test_utils.pl

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-11-21 14:50:34 UTC (rev 6790)
+++ trunk/ChangeLog     2015-11-21 14:57:34 UTC (rev 6791)
@@ -1,5 +1,11 @@
 2015-11-21  Gavin Smith  <address@hidden>
 
+       * tp/t/README: Mention run_all function.
+       * tp/t/test_utils.pl (test, run_all, output_texi_file): Comments 
+       added.
+
+2015-11-21  Gavin Smith  <address@hidden>
+
        * tp/t/plaintext.t (quote_node_names): New test.
        * tp/t/input_files/nodequote.texi: Input file.
        * tp/t/results/plaintext_tests/

Modified: trunk/tp/t/README
===================================================================
--- trunk/tp/t/README   2015-11-21 14:50:34 UTC (rev 6790)
+++ trunk/tp/t/README   2015-11-21 14:57:34 UTC (rev 6791)
@@ -24,8 +24,11 @@
 
   make check TESTS=t/03coverage_braces.t
 
-Most test files use a testing infrastructure from t/test_utils.pl.  In
-that case the reference output files for the test of a test category 
+Most test files use a testing infrastructure from t/test_utils.pl.
+The run_all function from that file runs the tests that have been 
+specified.
+
+In that case the reference output files for the test of a test category 
 $test_category.t file are in t/results/$test_category/.  For example, if 
 after running "make check" test-suite.log contains a line like:
 

Modified: trunk/tp/t/test_utils.pl
===================================================================
--- trunk/tp/t/test_utils.pl    2015-11-21 14:50:34 UTC (rev 6790)
+++ trunk/tp/t/test_utils.pl    2015-11-21 14:57:34 UTC (rev 6791)
@@ -666,6 +666,8 @@
   return ($errors, $result);
 }
 
+# Run a single test case.  Each test case is an array
+# [TEST_NAME, TEST_TEXT, PARSER_OPTIONS, CONVERTER_OPTIONS]
 sub test($$) 
 {
   my $self = shift;
@@ -682,6 +684,7 @@
   $test_text = shift @$test_case;
   $parser_options = shift @$test_case if (@$test_case);
   $converter_options = shift @$test_case if (@$test_case);
+
   my $test_file;
   if ($parser_options->{'test_file'}) {
     $test_file = $input_files_dir . $parser_options->{'test_file'};
@@ -1094,7 +1097,14 @@
   return $tests_count;
 }
 
-# if a $test_case_name is given, only run that test.
+# Main entry point for the tests.
+#   $NAME - a string, name of test
+#   $TEST_CASES - array of sub-tests
+#   If $TEST_CASE_NAME is given, only run that test.
+#   $GENERATE means to generate reference test results (-g from command line).
+#   $DEBUG for debugging.
+# The $ARG_COMPLETE variable is the -c option, to create Texinfo files for the
+# test cases.
 sub run_all($$;$$$)
 {
   my $name = shift;
@@ -1139,6 +1149,7 @@
   }
 }
 
+# Create a Texinfo file for a test case; used when -c option is given.
 sub output_texi_file($)
 {
   my $self = shift;