Asjusting unittest comments with one-line summaries

pkg/unittest/lib/unittest.dart

 // Copyright (c) 2013, 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.
 
 /// Support for writing Dart unit tests.
 ///
 /// For information on installing and importing this library, see the
 /// [unittest package on pub.dartlang.org]
 /// (http://pub.dartlang.org/packages/unittest).
 ///
@@ skipping 136 matching lines @@
 import 'src/configuration.dart';
 export 'src/configuration.dart';
 
 part 'src/simple_configuration.dart';
 part 'src/group_context.dart';
 part 'src/spread_args_helper.dart';
 part 'src/test_case.dart';
 
 Configuration _config;
 
-/// [Configuration] used by the unittest library. Note that if a
-/// configuration has not been set, calling this getter will create
-/// a default configuration.
+/// [Configuration] used by the unittest library.
+///
+/// Note that if a configuration has not been set, calling this getter will
+/// create a default configuration.
 Configuration get unittestConfiguration {
   if (_config == null) {
     _config = new Configuration();
   }
   return _config;
 }
 
 /// Sets the [Configuration] used by the unittest library.
 ///
 /// Throws a [StateError] if there is an existing, incompatible value.
@@ skipping 108 matching lines @@
   }
   ++_soloNestingLevel;
   try {
     test(spec, body);
   } finally {
     --_soloNestingLevel;
   }
 }
 
 /// Indicate that [callback] is expected to be called a [count] number of times
-/// (by default 1). The unittest framework will wait for the callback to run the
+/// (by default 1).
+///
+/// The unittest framework will wait for the callback to run the
 /// specified [count] times before it continues with the following test.  Using
 /// [expectAsync] will also ensure that errors that occur within [callback] are
 /// tracked and reported. [callback] should take 0 positional arguments (named
 /// arguments are not supported). [id] can be used to provide more
 /// descriptive error messages if the callback is called more often than
-/// expected. [max] can be used to specify an upper bound on the number of
+/// expected.
+///
+/// [max] can be used to specify an upper bound on the number of
 /// calls; if this is exceeded the test will fail (or be marked as in error if
 /// it was already complete). A value of 0 for [max] (the default) will set
 /// the upper bound to the same value as [count]; i.e. the callback should be
 /// called exactly [count] times. A value of -1 for [max] will mean no upper
 /// bound.
 ///
 /// [reason] is optional and is typically not supplied, as a reason is generated
 /// by the unittest package; if reason is included it is appended to the
 /// generated reason.
 Function expectAsync(Function callback,
     {int count: 1, int max: 0, String id, String reason}) =>
   new _SpreadArgsHelper(callback, count, max, id, reason).func;
 
 /// Indicate that [callback] is expected to be called until [isDone] returns
-/// true. The unittest framework check [isDone] after each callback and only
+/// true.
+///
+/// The unittest framework checks [isDone] after each callback and only
 /// when it returns true will it continue with the following test. Using
 /// [expectAsyncUntil] will also ensure that errors that occur within
 /// [callback] are tracked and reported. [callback] should take 0 positional
 /// arguments (named arguments are not supported). [id] can be used to
 /// identify the callback in error messages (for example if it is called
 /// after the test case is complete).
 ///
 /// [reason] is optional and is typically not supplied, as a reason is generated
 /// by the unittest package; if reason is included it is appended to the
 /// generated reason.
 Function expectAsyncUntil(Function callback, bool isDone(),
     {String id, String reason}) =>
   new _SpreadArgsHelper(callback, 0, -1, id, reason, isDone: isDone).func;
 
-/// Creates a new named group of tests. Calls to group() or test() within the
-/// body of the function passed to this will inherit this group's description.
+/// Creates a new named group of tests.
+///
+/// Calls to group() or test() within the body of the function passed to this
+/// named group will inherit this group's description.
 void group(String description, void body()) {
   ensureInitialized();
   _requireNotRunning();
   _currentContext = new _GroupContext(_currentContext, description);
   try {
     body();
   } catch (e, trace) {
     var stack = (trace == null) ? '' : ': ${trace.toString()}';
     _uncaughtErrorMessage = "${e.toString()}$stack";
   } finally {
@@ skipping 15 matching lines @@
     _testCases.clear();
   }
   ++_soloNestingLevel;
   try {
     group(description, body);
   } finally {
     --_soloNestingLevel;
   }
 }
 
-/// Register a [setUp] function for a test [group]. This function will
-/// be called before each test in the group is run.
+/// Register a [setUp] function for a test [group].
+///
+/// This function will be called before each test in the group is run.
 /// [setUp] and [tearDown] should be called within the [group] before any
 /// calls to [test]. The [setupTest] function can be asynchronous; in this
 /// case it must return a [Future].
 void setUp(Function setupTest) {
   _requireNotRunning();
   _currentContext.testSetup = setupTest;
 }
 
-/// Register a [tearDown] function for a test [group]. This function will
-/// be called after each test in the group is run. Note that if groups
-/// are nested only the most locally scoped [teardownTest] function will be run.
-/// [setUp] and [tearDown] should be called within the [group] before any
-/// calls to [test]. The [teardownTest] function can be asynchronous; in this
-/// case it must return a [Future].
+/// Register a [tearDown] function for a test [group].
+///
+/// This function will be called after each test in the group is run.
+///
+/// Note that if groups are nested only the most locally scoped [teardownTest]
+/// function will be run. [setUp] and [tearDown] should be called within the
+/// [group] before any calls to [test]. The [teardownTest] function can be
+/// asynchronous; in this case it must return a [Future].
 void tearDown(Function teardownTest) {
   _requireNotRunning();
   _currentContext.testTeardown = teardownTest;
 }
 
 /// Advance to the next test case.
 void _nextTestCase() {
   _currentTestCaseIndex++;
   _runTest();
 }
 
 /// Handle errors that happen outside the tests.
 // TODO(vsm): figure out how to expose the stack trace here
 // Currently e.message works in dartium, but not in dartc.
 void handleExternalError(e, String message, [stack]) {
   var msg = '$message\nCaught $e';
 
   if (currentTestCase != null) {
     currentTestCase._error(msg, stack);
   } else {
     _uncaughtErrorMessage = "$msg: $stack";
   }
 }
 
-/// Filter the tests. [testFilter] can be a [RegExp], a [String] or a
-/// predicate function. This is different to enabling/disabling tests
+/// Filter the tests by [testFilter].
+///
+/// [testFilter] can be a [RegExp], a [String] or a
+/// predicate function. This is different from enabling or disabling tests
 /// in that it removes the tests completely.
 void filterTests(testFilter) {
   var filterFunction;
   if (testFilter is String) {
     RegExp re = new RegExp(testFilter);
     filterFunction = (t) => re.hasMatch(t.description);
   } else if (testFilter is RegExp) {
     filterFunction = (t) => testFilter.hasMatch(t.description);
   } else if (testFilter is Function) {
     filterFunction = testFilter;
@@ skipping 143 matching lines @@
 /// Signature for a test function.
 typedef dynamic TestFunction();
 
 /// A flag that controls whether we hide unittest and core library details in
 /// exception stacks.
 ///
 /// Useful to disable when debugging unittest or matcher customizations.
 bool formatStacks = true;
 
 /// A flag that controls whether we try to filter out irrelevant frames from
-/// the stack trace. Requires formatStacks to be set.
+/// the stack trace.
+///
+/// Requires [formatStacks] to be set.
 bool filterStacks = true;
 
 void _requireNotRunning() {
   if (_currentTestCaseIndex != -1) {
     throw new StateError('Not allowed when tests are running.');
   }
 }