Add dartdoc comments to Dart testing infrastructure.

Add dartdoc comments to Dart testing infrastructure.


BUG=
TEST=

Committed: https://code.google.com/p/dart/source/detail?r=4079

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

A couple of nits but otherwise this is fantastic. Thanks for doing this!

LGTM.

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
File tools/testing/dart/test_runner.dart (right):

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:25: * its output.  Running a test involves
starting a separate process, with
Style nit, but editors (people, not software) these days generally don't
encourage two spaces after a period anymore.

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:32: * in the TestCase.  The [TestOutput]
instance is responsible for evaluating
I would probably only put the first occurrence of a name in []. I wouldn't want
to overload the reader with redundant links.

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:36: * The TestCase has a callback function,
completedHandler, that is run when
[completedHandler]

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:468: * about its list of tests, and retrieve
that information when it is called
"retrieves"

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
File tools/testing/dart/test_suite.dart (right):

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_suite.dart:17: * This module includes:
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".

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_suite.dart:33: * Call the callback function onTest with
a [TestCase] argument for each
[onTest] and the other parameters mentioned.

You can reference parameter names with [] too.

[Mads Ager (google), 2012-02-08 07:40:46]

lgtm

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

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
File tools/testing/dart/test_runner.dart (right):

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:25: * its output.  Running a test involves
starting a separate process, with
On 2012/02/07 18:41:24, Bob Nystrom wrote:
> Style nit, but editors (people, not software) these days generally don't
> encourage two spaces after a period anymore.

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.

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_runner.dart:468: * about its list of tests, and retrieve
that information when it is called
On 2012/02/07 18:41:24, Bob Nystrom wrote:
> "retrieves"
this is short for "may retrieve".  Adding "may"

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
File tools/testing/dart/test_suite.dart (right):

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_suite.dart:33: * Call the callback function onTest with
a [TestCase] argument for each
On 2012/02/07 18:41:24, Bob Nystrom wrote:
> [onTest] and the other parameters mentioned.
> 
> You can reference parameter names with [] too.

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:47]

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
File tools/testing/dart/test_suite.dart (right):

https://chromiumcodereview.appspot.com/9347023/diff/1/tools/testing/dart/test...
tools/testing/dart/test_suite.dart:33: * Call the callback function onTest with
a [TestCase] argument for each
On 2012/02/09 15:47:39, Bill Hesse wrote:
> On 2012/02/07 18:41:24, Bob Nystrom wrote:
> > [onTest] and the other parameters mentioned.
> > 
> > You can reference parameter names with [] too.
> 
> 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?

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