Add dartdoc comments to Dart testing infrastructure.

tools/testing/dart/test_suite.dart

Index: tools/testing/dart/test_suite.dart
diff --git a/tools/testing/dart/test_suite.dart b/tools/testing/dart/test_suite.dart
index f96273e2a67104b3fc7226a18004e24cbf1ea4fb..5f096ff786c9949381598c9c1fab069aaba17206 100644
--- a/tools/testing/dart/test_suite.dart
+++ b/tools/testing/dart/test_suite.dart
@@ -11,12 +11,37 @@
 
 #source("browser_test.dart");
 
+/**
+ * Classes and methods for enumerating and preparing tests.
+ *
+ * This module includes:

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

Add a blank line after this one, and the subsequent list should be correctly
list formatted. Also, in Dart lingo this is a "library" and not a "module".

+ * - Creating tests by listing all the Dart files in certain directories,
+ *   and creating [TestCase]s for those files that meet the relevant criteria.
+ * - Preparing tests, including copying files and frameworks to temporary
+ *   directories, and computing the command line and arguments to be run.
+ */
+
+/**
+ * A [TestSuite] represents a collection of tests.  It creates a [TestCase]
+ * object for each test to be run, and passes the test cases to a callback.
+ *
+ * Most [TestSuites] represent a directory or directory tree containing tests,
+ * and a status file containing the expected results when these tests are run.
+ */
 interface TestSuite {
+  /**
+   * Call the callback function onTest with a [TestCase] argument for each

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

[onTest] and the other parameters mentioned.

You can reference parameter names with [] too.

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

How can we reference fields or functions of class B, in the comment for a method
of class A?  Is there a way to write this?

[Bob Nystrom, 2012/02/09 21:23:48]

I believe [B.field] should do that. If not, it's a bug. :)

+   * test in the suite.  When all tests have been processed, call onDone.
+   *
+   * The testCache argument provides a persistent store that can be used to
+   * cache information about the test suite, so that directories do not need
+   * to be listed each time.  If the tests require a temporary directory for
+   * their files, they can get one from globalTempDir.
+   */
   void forEachTest(Function onTest, Map testCache, String globalTempDir(),
                    [Function onDone]);
 }
 
-
 class CCTestListerIsolate extends Isolate {
   CCTestListerIsolate() : super.heavy();
 
@@ -52,6 +77,14 @@ class CCTestListerIsolate extends Isolate {
 }
 
 
+/**
+ * A specialized [TestSuite] that runs tests written in C to unit test
+ * the Dart virtual machine and its API.
+ *
+ * The tests are compiled into a monolithic executable by the build step.
+ * The executable lists its tests when run with the --list command line flag.
+ * Individual tests are run by specifying them on the command line.
+ */ 
 class CCTestSuite implements TestSuite {
   Map configuration;
   final String suiteName;
@@ -148,6 +181,10 @@ class TestInformation {
 }
 
 
+/**
+ * A standard [TestSuite] implementation that searches for tests in a
+ * directory, and creates [TestCase]s that compile and/or run them.
+ */ 
 class StandardTestSuite implements TestSuite {
   Map configuration;
   String suiteName;
@@ -168,6 +205,10 @@ class StandardTestSuite implements TestSuite {
                     List<String> this.statusFilePaths)
     : dartDir = TestUtils.dartDir();
 
+  /**
+   * The default implementation assumes a file is a test if
+   * it ends in "Test.dart".
+   */ 
   bool isTestFile(String filename) => filename.endsWith("Test.dart");
 
   bool listRecursively() => false;
@@ -354,6 +395,17 @@ class StandardTestSuite implements TestSuite {
     }
   }
 
+  /**
+   * The [StandardTestSuite] has support for testing components that
+   * compile a test from Dart to Javascript, and then run the resulting
+   * Javascript.  This function creates a working directory to hold the
+   * Javascript version of the test, and copies the appropriate framework
+   * files to that directory.  It creates a [BrowserTestCase], which has
+   * two sequential steps to be run by the [ProcessQueue when] the test is
+   * executed: a compilation
+   * step and an execution step, both with the appropriate executable and
+   * arguments.
+   */
   void enqueueBrowserTest(String filename,
                           String testName,
                           Map optionsFromFile,
@@ -520,9 +572,23 @@ class StandardTestSuite implements TestSuite {
       configuration['component'] == 'chromium';
 
   /**
-   * Create a directory for the generated test.  Drop the path to the
-   * dart checkout and the final ".dart" from the test path, and replace
-   * all path separators with underscores.
+   * Create a directory for the generated test.  If a Dart language test
+   * needs to be run in a browser, the Dart test needs to be embedded in
+   * an HTML page, with a testing framework based on scripting and DOM events.
+   * These scripts and pages are written to a generated_test directory,
+   * usually inside the build directory of the checkout.
+   *
+   * Some tests, such as those using the dartc compiler, need to be run
+   * with an empty directory as the compiler's work directory.  These
+   * tests are copied to a subdirectory of a system-provided temporary
+   * directory, which is deleted at the end of the test run unless the
+   * --keep-temporary-files flag is given.
+   *
+   * Those tests which are already HTML web applications (web tests), with
+   * resources including CSS files and HTML files, need to be compiled into
+   * a work directory where the relative URLS to the resources work.
+   * We use a subdirectory of the build directory that is the same number
+   * of levels down in the checkout as the original path of the web test.
    */
   Directory createOutputDirectory(String testPath, String optionsName) {
     String testUniqueName =