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.
  */
+#library("test_runner");
+
+#import("dart:io");
+#import("status_file_parser.dart");
+#import("test_progress.dart");
+#import("test_suite.dart");
 
 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
+ * 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
+ * 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
+ * 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;
-  /** 
-   * Indicates if this test is a rerun, to compensate for flaky browser tests. 
+  /**
+   * Indicates if this test is a rerun, to compensate for flaky browser tests.
    */
   bool isRerun;
 
   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';
     }
     isRerun = false;
   }
 }
 
 
+/**
+ * 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;
 
-  RunningProcess(this.testCase);
+  RunningProcess(TestCase this.testCase);
 
   void exitHandler(int exitCode) {
     new TestOutput(testCase, exitCode, timedOut, stdout,
                    stderr, new Date.now().difference(startTime));
     process.close();
     timeoutTimer.cancel();
     if (testCase.output.unexpectedOutput && testCase.configuration['verbose']) {
       print(testCase.output.stdout);
       print(testCase.output.stderr);
     }
-    if (testCase is BrowserTestCase && testCase.output.unexpectedOutput && 
+    if (testCase is BrowserTestCase && testCase.output.unexpectedOutput &&
         !testCase.isRerun) {
       // Selenium tests can be flaky. Try rerunning.
       testCase.isRerun = true;
       this.timedOut = false;
       this.start();
     } else {
       testCase.completed();
     }
   }
 
   void compilerExitHandler(int exitCode) {
     if (exitCode != 0) {
       stderr.add('test.dart: Compilation step failed (exit code $exitCode)\n');
       exitHandler(exitCode);
     } else {
       process.close();
       stderr.add('test.dart: Compilation finished, starting execution\n');
       stdout.add('test.dart: Compilation finished, starting execution\n');
       runCommand(testCase.executablePath, testCase.arguments, exitHandler);
     }
   }
-      
+
   Function makeReadHandler(StringInputStream source, List<String> destination) {
     return () {
       if (source.closed) return;  // TODO(whesse): Remove when bug is fixed.
       var line = source.readLine();
       while (null != line) {
         destination.add(line);
         line = source.readLine();
       }
     };
   }
@@ skipping 59 matching lines @@
   bool get active() => _currentTest != null;
 
   void startTest(TestCase testCase) {
     _currentTest = testCase;
     if (_process === null) {
       // Start process if not yet started.
       _executable = testCase.executablePath;
       _startProcess(() {
         doStartTest(testCase);
       });
-    } else if (testCase.executablePath != _executable) { 
+    } else if (testCase.executablePath != _executable) {
       // Restart this runner with the right executable for this test
       // if needed.
       _executable = testCase.executablePath;
       _process.exitHandler = (exitCode) {
         _process.close();
         _startProcess(() {
           doStartTest(testCase);
         });
       };
       _process.kill();
     } else {
       doStartTest(testCase);
     }
   }
 
   void terminate() {
     if (_process !== null) {
       _process.exitHandler = (exitCode) {
         _process.close();
       };
       _process.kill();
-    }  
+    }
   }
 
   void doStartTest(TestCase testCase) {
     _startTime = new Date.now();
     _testStdout = new List<String>();
     _testStderr = new List<String>();
     _stdoutStream.lineHandler = _readOutput(_stdoutStream, _testStdout);
     _stderrStream.lineHandler = _readOutput(_stderrStream, _testStderr);
     _timer = new Timer(_timeoutHandler(testCase), testCase.timeout * 1000);
     _process.stdin.write(_createArgumentsLine(testCase.arguments).charCodes());
@@ skipping 50 matching lines @@
     _startProcess(() {
       _reportResult(">>> TEST CRASH");
     });
   }
 
   Function _timeoutHandler(TestCase test) {
     return (ignore) {
       _process.exitHandler = (exitCode) {
         _process.close();
         _startProcess(() {
-          _reportResult(">>> TEST TIMEOUT");  
+          _reportResult(">>> TEST TIMEOUT");
         });
       };
       _process.kill();
     };
   }
 
   void _startProcess(then) {
     _process = new Process.start(_executable, ['-batch']);
     _stdoutStream = new StringInputStream(_process.stdout);
     _stderrStream = new StringInputStream(_process.stderr);
     _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 TestSuites 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.
+ *
+ * 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 may retrieve that information when it is called
+ * 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;
   String _temporaryDirectory;
   // For dartc batch processing we keep a list of batch processes.
   List<DartcBatchRunnerProcess> _batchProcesses;
+
   // Cache information about test cases per test suite. For multiple
   // configurations there is no need to repeatedly search the file
   // system, generate tests, and search test files for options.
   Map<String, List<TestInformation>> _testCache;
 
   ProcessQueue(int this._maxProcesses,
                String progress,
                Date startTime,
                bool printTiming,
                Function this._enqueueMoreWork,
                [bool this._verbose = false,
                 bool this._listTests = false,
                 bool this._keepGeneratedTests = false])
       : _tests = new Queue<TestCase>(),
         _progress = new ProgressIndicator.fromName(progress,
                                                    startTime,
                                                    printTiming),
         _batchProcesses = new List<DartcBatchRunnerProcess>(),
         _testCache = new Map<String, List<TestInformation>>() {
     if (!_enqueueMoreWork(this)) _progress.allDone();
   }
 
+  /**
+   * Registers a TestSuite so that all of its tests will be run.
+   */
   void addTestSuite(TestSuite testSuite) {
     _activeTestListers++;
     testSuite.forEachTest(_runTest, _testCache, globalTemporaryDirectory,
                           _testListerDone);
   }
 
   void _testListerDone() {
     _activeTestListers--;
     _checkDone();
   }
@@ skipping 98 matching lines @@
           test.displayName != 'dartc/junit_tests') {
         _ensureDartcBatchRunnersStarted(test.executablePath);
         _getDartcBatchRunnerProcess().startTest(test);
       } else {
         new RunningProcess(test).start();
       }
       _numProcesses++;
     }
   }
 }