documented component

tools/test.dart

Index: tools/test.dart
diff --git a/tools/test.dart b/tools/test.dart
index 80545b1d1c242e87c57e32f167ac964a2303dc40..df7299676f5ddbbb5b6c9037a466cb2740487bcf 100755
--- a/tools/test.dart
+++ b/tools/test.dart
@@ -3,6 +3,51 @@
 // 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 checkin suite.  This checkin

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

I never heard the term 'checkin suite' before, I'm not sure what it means. I was
expecting you'd say 'test suite'.

[mattsh, 2012/03/05 17:49:09]

Done.

+ * suite is used to test:
+ *
+ *     1. the dart vm
+ *     2. the frog compiler (compiles dart to js)

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

maybe mention that we ensure the gen code runs correctly in multiple browsers
(DumpRenderTree, chrome, FF, ie)

[mattsh, 2012/03/05 17:49:09]

I just wanted this list here to be a very quick summary of what is being tested,
so I don't think that quite fits here.

+ *     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.)

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

weird indent here. Maybe align with 'other'?
6. other ...
   io libraries...

[mattsh, 2012/03/05 17:49:09]

Just the normal 4 space line continuation indent.  (I didn't want to align with
"other" since then it looks like it might be a distinct item in the list but
missing its number.)

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

I was expecting expecting +4 from the bullet, not from the start of the text.

[mattsh, 2012/03/05 18:00:17]

OK, but +4 from the bullet will put it just one space in from the first word,
which looks a bit strange.

+ *
+ * This script is normally invoked by test.py.  (Test.py finds the dart vm
+ * and passses along all command line arguments to this script.)
+ *
+ * Most of the command line arguments to this script are straightforward and
+ * are documented in [tools/testing/test_options.dart]

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

I believe the notation [something] is only to point to symbols in the code (a
variable, method, class), but not files. Maybe change to [TestOptionParser] or
use quotes.

[mattsh, 2012/03/05 17:49:09]

OK, changed to quotes now.

+ *
+ * The "component" argument is complicated and is documented here.

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

I'd change this a bit - maybe reorder by saying: 

Test.py takes many command line arguments. The "component" argument defines
which part of the system is being tested and how. Here is a detail description
for what each component means:
  * vm: ...
  ...

All other arguments are straightforward and documented in test_options.dart

[mattsh, 2012/03/05 17:49:09]

OK, reworded and shortened this text.

+ *
+ * Allowable values of "component"
+ *
+ *   vm: run dart code on the standalone dart vm

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

(nit): make this also bulleted, fix indentation also here (I might prefer here
using alignment rather than +4)

  - vm: ...
  - frog: compile ...
          run the resulting ...
  - leg: compile ...
         run ...
  - ...

[mattsh, 2012/03/05 17:49:09]

slightly prefer to keep as is

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

please consider adding the bullet, I believe if we run this file by dartdoc, it
will be formatted better with them.

[mattsh, 2012/03/05 18:00:17]

Ah, good point.  I didn't know dartdoc picks up the bullets, ok added them.

+ *   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 dartium

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

actually we run it in a dartium-DumpRenderTree (a headless version of dartium)

[mattsh, 2012/03/05 17:49:09]

OK, thanks (siggi and I just chatted).  Updated comment to explain this.

+ *   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 DumpRenderTree

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

DumpRenderTree (a headless version of chromium)

[mattsh, 2012/03/05 17:49:09]

Done.

+ *   legium: compile dart code by running leg on the standalone dart vm,
+ *       and run the resulting javascript in 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

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

add closing paren

[mattsh, 2012/03/05 17:49:09]

Done.

+ *
+ *

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

remove extra lines

[mattsh, 2012/03/05 17:49:09]

Done.

+ */
+
+

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

here too

[mattsh, 2012/03/05 17:49:09]

Done.

 #library("test");
 
 #import("testing/dart/test_runner.dart");