documented component

tools/test.dart

Index: tools/test.dart
diff --git a/tools/test.dart b/tools/test.dart
index 80545b1d1c242e87c57e32f167ac964a2303dc40..7e5232bdcb2b495515531e6ca783b61ab7ab7cbc 100755
--- a/tools/test.dart
+++ b/tools/test.dart
@@ -3,6 +3,49 @@
 // 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.
 
+/**
+ * This file is the entrypoint of the dart test suite.  This suite is used
+ * to test:
+ *
+ *     1. the dart vm
+ *     2. the frog compiler (compiles dart to js)
+ *     3. the leg compiler (also compiles dart to js)
+ *     4. the dartc static analyzer
+ *     5. the dart core library
+ *     6. other standard dart libraries (DOM bindings, ui libraries,
+ *            io libraries etc.)
+ *
+ * This script is normally invoked by test.py.  (test.py finds the dart vm
+ * and passses along all command line arguments to this script.)
+ *
+ * The command line args of this script are documented in
+ * "tools/testing/test_options.dart".
+ *
+ * The the "component" command line arg can be:

[Siggi Cherem (dart-lang), 2012/03/05 17:54:25]

delete 'the'

+ *
+ *   vm: run dart code on the standalone dart vm

[ahe, 2012/03/05 18:00:46]

Instead of a comment, how about moving it to TestOptionsParser in
dart/tools/testing/dart/test_options.dart.

Instead of the string 'The component to test against', print the contents of
this comment.

[mattsh, 2012/03/05 18:07:36]

I considered that, and it's a possibility, but the problem is that it doesn't
fit in well with all the other flags that  only require a single line of
documentation.  (Putting this big multiline string in the middle of all those
other flags didn't look so good.)  Perhaps I should change the existing comment
to point people to this file?

+ *   frog: compile dart code by running frog on the standalone dart vm, and
+ *       run the resulting javascript on D8 
+ *   leg: compile dart code by running leg on the standalone dart vm, and
+ *       run the resulting javascript on D8.
+ *   frogsh: compile dart code by running frog on node.js, and run the
+ *       resulting javascript on the same instance of node.js
+ *   dartium: run dart code in a <script type="application/dart"> tag in a
+ *       dartium build of DumpRenderTree
+ *   chromium: obsolete, not used (TODO - remove this)
+ *   frogium: compile dart code by running frog on the standalone dart vm,
+ *       and run the resulting javascript in a javascript <script> tag in
+ *       a dartium build of DumpRenderTree
+ *   legium: compile dart code by running leg on the standalone dart vm,
+ *       and run the resulting javascript in a javascript <script> tag in
+ *       a dartium build of DumpRenderTree
+ *   webdriver: compile dart code by running frog on the standalone dart vm,
+ *       and then run the resulting javascript in a browser that
+ *       is specified by the --browser switch
+ *   dartc: run dart code through the dartc static analyzer (does not execute
+ *       dart code)
+ */
+
 #library("test");
 
 #import("testing/dart/test_runner.dart");