pkg/unittest: fixed docs

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 65 matching lines @@
  *         });
  *       });
  *     }
  *
  * Asynchronous tests: if callbacks expect between 0 and 2 positional arguments,
  * depending on the suffix of expectAsyncX(). expectAsyncX() will wrap a
  * function into a new callback and will not consider the test complete until
  * that callback is run. A count argument can be provided to specify the number
  * of times the callback should be called (the default is 1).
  *
+ *     import 'dart:async';
  *     import 'package:unittest/unittest.dart';
- *     import 'dart:isolate';
- *     main() {
+ *     void main() {
  *       test('callback is executed once', () {
  *         // wrap the callback of an asynchronous call with [expectAsync0] if
  *         // the callback takes 0 arguments...
  *         var timer = Timer.run(expectAsync0(() {
  *           int x = 2 + 3;
  *           expect(x, equals(5));
  *         }));
  *       });
  *
  *       test('callback is executed twice', () {
  *         var callback = expectAsync0(() {
  *           int x = 2 + 3;
  *           expect(x, equals(5));
  *         }, count: 2); // <-- we can indicate multiplicity to [expectAsync0]
  *         Timer.run(callback);
  *         Timer.run(callback);
  *       });
  *     }
  *
- * expectAsyncX() will wrap the callback code in a try/catch handler to handle
- * exceptions (treated as test failures). There may be times when the number of
- * times a callback should be called is non-deterministic. In this case a dummy
- * callback can be created with expectAsync0((){}) and this can be called from
- * the real callback when it is finally complete. In this case the body of the
- * callback should be protected within a call to guardAsync(); this will ensure
- * that exceptions are properly handled.
+ * expectAsyncX() will wrap the callback code and block the completion of the
+ * test until the wrapped callback has been called the specified number of times
+ * -- the default is 1. There may be times when the number of times a callback
+ * should be called is non-deterministic. In this case a dummy callback can be
+ * created with expectAsync0((){}) and this can be called from the real callback
+ * when it is finally complete.
  *
  * A variation on this is expectAsyncUntilX(), which takes a callback as the
  * first parameter and a predicate function as the second parameter; after each
  * time * the callback is called, the predicate function will be called; if it
  * returns false the test will still be considered incomplete.
  *
  * Test functions can return [Future]s, which provide another way of doing
  * asynchronous tests. The test framework will handle exceptions thrown by
  * the Future, and will advance to the next test when the Future is complete.
- * It is still important to use expectAsync/guardAsync with any parts of the
- * test that may be invoked from a top level context (for example, with
- * Timer.run()], as the Future exception handler may not capture exceptions
- * in such code.
+ *
+ *     import 'dart:async';
+ *     import 'package:unittest/unittest.dart';
+ *     void main() {
+ *       test('test that time has passed', () {
+ *         var duration = const Duration(milliseconds: 200);
+ *         var time = new DateTime.now();
+ *
+ *         return new Future.delayed(duration).then((_) {
+ *           var delta = new DateTime.now().difference(time);
+ *
+ *           expect(delta, greaterThanOrEqualTo(duration));
+ *         });
+ *       });
+ *     }
  *
  * Note: Due to some language limitations we have to use different functions
  * depending on the number of positional arguments of the callback. In the
  * future, we plan to expose a single `expectAsync` function that can be used
  * regardless of the number of positional arguments. This requires new langauge
  * features or fixes to the current spec (e.g. see
  * [Issue 2706](http://dartbug.com/2706)).
  */
 library unittest;
 
@@ skipping 564 matching lines @@
 
   if (!filterStacks) return trace;
 
   // Format the stack trace by removing everything above TestCase._runTest,
   // which is usually going to be irrelevant. Also fold together unittest and
   // core library calls so only the function the user called is visible.
   return new Trace(trace.frames.takeWhile((frame) {
     return frame.package != 'unittest' || frame.member != 'TestCase._runTest';
   })).terse.foldFrames((frame) => frame.package == 'unittest' || frame.isCore);
 }