Removed asyncTest and improved comments.

lib/unittest/unittest.dart

Index: lib/unittest/unittest.dart
===================================================================
--- lib/unittest/unittest.dart	(revision 8133)
+++ lib/unittest/unittest.dart	(working copy)
@@ -17,7 +17,9 @@
  *    class.
  *  * Configuration: The framework can be adapted by calling [configure] with a
  *    [Configuration].  Common configurations can be found in this package
- *    under: 'dom\_config.dart', 'html\_config.dart', and 'vm\_config.dart'.
+ *    under: 'dom\_config.dart' (deprecated), 'html\_config.dart' (for running
+ *    tests compiled to Javascript in a browser), and 'vm\_config.dart' (for
+ *    running native Dart tests on the VM).
  *
  * ##Examples##
  *
@@ -67,7 +69,11 @@
  *       });
  *     }
  *
- * Asynchronous tests: if callbacks expect between 0 and 2 positional arguments.
+ * Asynchronous tests: if callbacks expect between 0 and 2 positional arguments,
+ * depending on the suffix of expectAsyncX(). expectAsyncX() will wrap a function

[Emily Fortuna, 2012/05/31 17:09:28]

Char > 80 here on this line and below. 

[gram, 2012/05/31 17:38:42]

Done.

+ * 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('path-to-dart/lib/unittest/unitest.dart');
  *     #import('dart:dom_deprecated');
@@ -91,6 +97,14 @@
  *       });
  *     }
  *
+ * 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.
+ *
  * 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
@@ -222,25 +236,6 @@
 }
 
 /**
- * Creates a new async test case with the given description and body. The
- * description will include the descriptions of any surrounding group()
- * calls.
- */
-// TODO(sigmund): deprecate this API
-void asyncTest(String spec, int callbacks, TestFunction body) {
-  ensureInitialized();
-
-  final testCase = new TestCase(
-      _tests.length + 1, _fullSpec(spec), body, callbacks);
-  _tests.add(testCase);
-
-  if (callbacks < 1) {
-    testCase.error(
-        'Async tests must wait for at least one callback ', '');
-  }
-}
-
-/**
  * Creates a new test case with the given description and body. The
  * description will include the descriptions of any surrounding group()
  * calls.
@@ -405,7 +400,7 @@
   }
 }
 
-/** Called by subclasses to indicate that an asynchronous test completed. */
+/* Called by subclasses to indicate that an asynchronous test completed. */

[Emily Fortuna, 2012/05/31 17:09:28]

Put the other * back, please.

[gram, 2012/05/31 17:38:42]

Done.

 void callbackDone() {
   // TODO (gram): we defer this to give the nextBatch recursive
   // stack a chance to unwind. This is a temporary hack but 
@@ -433,7 +428,9 @@
   });
 }
 
-/** Menchanism to notify that an error was caught outside of this library. */
+/** Utility function that can be used to notify the test framework that an

[Emily Fortuna, 2012/05/31 17:09:28]

If the comment spans multiple lines, make the first line only contain:
/**
 * Utility function...
 */

[gram, 2012/05/31 17:38:42]

Done.

+ *  error was caught outside of this library.
+ */
 void reportTestError(String msg, String trace) {
  if (_currentTest < _tests.length) {
     final testCase = _tests[_currentTest];