Add dartdoc comments to Dart testing infrastructure.

tools/testing/dart/test_runner.dart

Index: tools/testing/dart/test_runner.dart
diff --git a/tools/testing/dart/test_runner.dart b/tools/testing/dart/test_runner.dart
index d4a78e6c38704f18bfcaf99991f5dd8c95cc1075..18525c437f057a032cae8f134265773f67dda326 100644
--- a/tools/testing/dart/test_runner.dart
+++ b/tools/testing/dart/test_runner.dart
@@ -20,6 +20,22 @@
 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;
@@ -89,12 +105,18 @@ class TestCase {
 
 
 /**
- * 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,
@@ -122,8 +144,13 @@ class BrowserTestCase extends TestCase {
 }
 
 
+/**
+ * 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;
@@ -188,7 +215,16 @@ class TestOutput {
   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;
@@ -414,6 +450,24 @@ class DartcBatchRunnerProcess {
 }
 
 
+/**
+ * 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;