Add dartdoc comments to Dart testing infrastructure.

tools/testing/dart/test_suite.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_suite");
 
 #import("dart:io");
 #import("status_file_parser.dart");
 #import("test_runner.dart");
 #import("multitest.dart");
 
 #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();
 
   void main() {
     port.receive((String runnerPath, SendPort replyTo) {
       var p = new Process.start(runnerPath, ["--list"]);
       StringInputStream stdoutStream = new StringInputStream(p.stdout);
       List<String> tests = new List<String>();
       stdoutStream.lineHandler = () {
         String line = stdoutStream.readLine();
@@ skipping 15 matching lines @@
           replyTo.send(test);
         }
         replyTo.send("");
       };
       port.close();
     });
   }
 }
 
 
+/**
+ * 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;
   String runnerPath;
   final String dartDir;
   List<String> statusFilePaths;
   Function doTest;
   Function doDone;
   ReceivePort receiveTestName;
   TestExpectations testExpectations;
@@ skipping 76 matching lines @@
   Map optionsFromFile;
   bool isNegative;
   bool isNegativeIfChecked;
   bool hasFatalTypeErrors;
 
   TestInformation(this.filename, this.optionsFromFile, this.isNegative,
                   this.isNegativeIfChecked, this.hasFatalTypeErrors);
 }
 
 
+/**
+ * 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;
   String directoryPath;
   List<String> statusFilePaths;
   Function doTest;
   Function doDone;
   int activeTestGenerators = 0;
   bool listingDone = false;
   TestExpectations testExpectations;
   List<TestInformation> cachedTests;
   final String dartDir;
   Function globalTemporaryDirectory;
 
   StandardTestSuite(Map this.configuration,
                     String this.suiteName,
                     String this.directoryPath,
                     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;
 
   String shellPath() => TestUtils.dartShellFileName(configuration);
 
   List<String> additionalOptions(String filename) => [];
 
   void forEachTest(Function onTest, Map testCache, String globalTempDir(),
                    [Function onDone = null]) {
@@ skipping 166 matching lines @@
       DoMultitest(filename,
                   TestUtils.buildDir(configuration),
                   directoryPath,
                   createTestCase,
                   testGeneratorDone);
     } else {
       createTestCase(filename, optionsFromFile['isNegative']);
     }
   }
 
+  /**
+   * 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,
                           Set<String> expectations,
                           bool isNegative) {
     if (optionsFromFile['isMultitest']) return;
     bool isWebTest = optionsFromFile['containsDomImport'];
     bool isLibraryDefinition = optionsFromFile['isLibraryDefinition'];
     if (!isLibraryDefinition && optionsFromFile['containsSourceOrImport']) {
       print('Warning for $filename: Browser tests require #library ' +
@@ skipping 146 matching lines @@
           optionsFromFile['isNegative']);
       doTest(testCase);
     }
   }
 
   bool get requiresCleanTemporaryDirectory() =>
       configuration['component'] == 'dartc' ||
       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 =
         testPath.substring(dartDir.length + 1, testPath.length - 5);
     testUniqueName = testUniqueName.replaceAll('/', '_');
     testUniqueName += '-$optionsName';
 
     // Create '[build dir]/generated_tests/$component/$testUniqueName',
       // including any intermediate directories that don't exist.
     String debugMode =
@@ skipping 527 matching lines @@
  * $noCrash tests are expected to be flaky but not crash
  * $pass tests are expected to pass
  * $failOk tests are expected to fail that we won't fix
  * $fail tests are expected to fail that we should fix
  * $crash tests are expected to crash that we should fix
  * $timeout tests are allowed to timeout
 """;
     print(report);
    }
 }