Add dartdoc comments to Dart testing infrastructure.

tools/testing/dart/test_runner.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #library("test_runner");
 
 #import("dart:io");
 #import("status_file_parser.dart");
 #import("test_progress.dart");
 #import("test_suite.dart");
 
 /**
  * Classes and methods for executing tests.
  *
  * This module includes:
  * - Managing parallel execution of tests, including timeout checks.
  * - Evaluating the output of each test as pass/fail/crash/timeout.
  */
 
 final int NO_TIMEOUT = 0;
 
 
+/**
+ * [TestCase] contains all the information needed to run a test and evaluate
+ * its output.  Running a test involves starting a separate process, with

[Bob Nystrom, 2012/02/07 18:41:24]

Style nit, but editors (people, not software) these days generally don't
encourage two spaces after a period anymore.

[Bill Hesse, 2012/02/09 15:47:39]

But they assume everything is in a proportional font, and when this is formatted
for the web, HTML ignores the extra space anyway.  So we get two spaces in
monospace, and one space in proportional.

+ * the executable and arguments given by the TestCase, and recording its
+ * stdout and stderr output streams, and its exit code.  TestCase only
+ * contains static information about the test; actually running the test is
+ * performed by [ProcessQueue] using a [RunningProcess] object.
+ *
+ * The output information is stored in a [TestOutput] instance contained
+ * in the TestCase.  The [TestOutput] instance is responsible for evaluating

[Bob Nystrom, 2012/02/07 18:41:24]

I would probably only put the first occurrence of a name in []. I wouldn't want
to overload the reader with redundant links.

+ * if the test has passed, failed, crashed, or timed out, and the TestCase
+ * has information about what the expected result of the test should be.
+ *
+ * The TestCase has a callback function, completedHandler, that is run when

[Bob Nystrom, 2012/02/07 18:41:24]

[completedHandler]

+ * the test is completed.
+ */
 class TestCase {
   String executablePath;
   List<String> arguments;
   Map configuration;
   String commandLine;
   String displayName;
   TestOutput output;
   bool isNegative;
   Set<String> expectedOutcomes;
   Function completedHandler;
@@ skipping 49 matching lines @@
     final mode = configuration['mode'];
     final arch = configuration['arch'];
     return "$component ${mode}_$arch";
   }
 
   void completed() { completedHandler(this); }
 }
 
 
 /**
- * BrowserTestCase has an extra compilation command that is run by
- * RunningProcess.start(), and it checks conditions on the test output
- * in TestOutput.didFail().
+ * BrowserTestCase has an extra compilation command that is run in a separate
+ * process, before the regular test is run as in the base class [TestCase].
+ * If the compilation command fails, then the rest of the test is not run.
  */
 class BrowserTestCase extends TestCase {
+  /**
+   * The executable that is run in a new process in the compilation phase.
+   */
   String compilerPath;
+  /**
+   * The arguments for the compilation command.
+   */
   List<String> compilerArguments;
 
   BrowserTestCase(displayName,
                     this.compilerPath,
                     this.compilerArguments,
                     executablePath,
                     arguments,
                     configuration,
                     completedHandler,
                     expectedOutcomes,
                     [isNegative = false]) : super(displayName,
                                                   executablePath,
                                                   arguments,
                                                   configuration,
                                                   completedHandler,
                                                   expectedOutcomes,
                                                   isNegative) {
     if (compilerPath != null) {
       commandLine = 'execution command: $commandLine';
       String compilationCommand =
           '$compilerPath ${Strings.join(compilerArguments, " ")}';
       commandLine = 'compilation command: $compilationCommand\n$commandLine';
     }
   }
 }
 
 
+/**
+ * TestOutput records the output of a completed test: the process's exit code,
+ * the standard output and standard error, whether the process timed out, and
+ * the time the process took to run.  It also contains a pointer to the
+ * [TestCase] this is the output of.
+ */
 class TestOutput {
-  // The TestCase this is the output from.
   TestCase testCase;
   int exitCode;
   bool timedOut;
   bool failed = false;
   List<String> stdout;
   List<String> stderr;
   Duration time;
 
   TestOutput(this.testCase, this.exitCode, this.timedOut, this.stdout,
              this.stderr, this.time) {
@@ skipping 44 matching lines @@
         return testCase.isNegative;
       }
     }
     return true;
   }
 
   // Reverse result of a negative test.
   bool get hasFailed() => (testCase.isNegative ? !didFail : didFail);
 }
 
-
+/**
+ * A RunningProcess actually runs a test, getting the command lines from
+ * its [TestCase], starting the test process (and first, a compilation
+ * process if the [TestCase] is a [BrowserTestCase]), creating a timeout
+ * timer, and recording the results in a new [TestOutput] object, which it
+ * attaches to the [TestCase].  The lifetime of the RunningProcess is limited
+ * to the time it takes to start the process, run the process, and record
+ * the result; there are no pointers to it, so it should be available to 
+ * be garbage collected as soon as it is done.
+ */ 
 class RunningProcess {
   Process process;
   TestCase testCase;
   bool timedOut = false;
   Date startTime;
   Timer timeoutTimer;
   List<String> stdout;
   List<String> stderr;
   List<Function> handlers;
 
@@ skipping 205 matching lines @@
     _testStdout = new List<String>();
     _testStderr = new List<String>();
     _stdoutStream.lineHandler = _readOutput(_stdoutStream, _testStdout);
     _stderrStream.lineHandler = _readOutput(_stderrStream, _testStderr);
     _process.exitHandler = _exitHandler;
     _process.startHandler = then;
   }
 }
 
 
+/**
+ * ProcessQueue is the master control class, responsible for running all
+ * the tests in all the [TestSuite]s that have been registered.  It includes
+ * a rate-limited queue to run a limited number of tests in parallel,
+ * a ProgressIndicator which prints output when tests are started and
+ * and completed, and a summary report when all tests are completed,
+ * and counters to determine when all of the tests in all of the test suites
+ * have completed.
+ *
+ * [TestSuite] objects are registered with the ProcessQueue when it is
+ * created, and then the ProcessQueue requests them to enqueue their tests
+ * (asynchronously) by calling their "forEachTest" methods.
+ *
+ * Because multiple configurations may be run on each test suite, the
+ * ProcessQueue contains a cache in which a test suite may record information
+ * about its list of tests, and retrieve that information when it is called

[Bob Nystrom, 2012/02/07 18:41:24]

"retrieves"

[Bill Hesse, 2012/02/09 15:47:39]

this is short for "may retrieve".  Adding "may"

+ * upon to enqueue its tests again.
+ */
 class ProcessQueue {
   int _numProcesses = 0;
   int _activeTestListers = 0;
   int _maxProcesses;
   bool _verbose;
   bool _listTests;
   bool _keepGeneratedTests;
   Function _enqueueMoreWork;
   Queue<TestCase> _tests;
   ProgressIndicator _progress;
@@ skipping 133 matching lines @@
           test.displayName != 'dartc/junit_tests') {
         _ensureDartcBatchRunnersStarted(test.executablePath);
         _getDartcBatchRunnerProcess().startTest(test);
       } else {
         new RunningProcess(test).start();
       }
       _numProcesses++;
     }
   }
 }