pkg/unittest: Removed references to expectAsync[Until]X in docs

pkg/unittest: Removed references to expectAsync[Until]X in docs

fixed changelog
Moved to triple slash, fixed doc comments
whitespace formatting
tests: finals, annotating functions

R=sigmund@google.com

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

[kevmoo, 2014-03-25 00:55:49]

Lots of random goodness

...fixed that I published a -dev in the 0.10.1 rel notes.

[kevmoo, 2014-03-25 01:01:34]

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
File pkg/unittest/lib/unittest.dart (right):

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
pkg/unittest/lib/unittest.dart:107: /// There may be times when the number of
times a callback should be called is
This paragraph is tough to understand. Should we just nuke it?

[Siggi Cherem (dart-lang), 2014-03-25 17:33:18]

lgtm

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
File pkg/unittest/lib/unittest.dart (right):

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
pkg/unittest/lib/unittest.dart:107: /// There may be times when the number of
times a callback should be called is
On 2014/03/25 01:01:34, kevmoo wrote:
> This paragraph is tough to understand. Should we just nuke it?

Sure, an alternative here would be to explain it differently, for example: 

---
If you need to block the test until one of a several callbacks is invoked, you
can follow this pattern:
   // test will block until notifyDone is invoked
   var notifyDone = expectAsync(() {}); 
   bool aCalled = false;
   bool bCalled = false;
   someApi.run(() { aCalled = true; notifyDone(); });
   someOtherApi.run(() { aCalled = true; notifyDone(); });
   expect(aCalled || bCalled, isTrue);
   expect(aCalled && bCalled, isFalse);

---
We had this because people had a hard time coming up with this pattern before,
so it was important to bring it up. Now that we have 'return Future', you could
also create a completer and mark it as done when you need it to, so maybe it's
not as relevant anymore.

[kevmoo, 2014-03-25 19:43:48]

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
File pkg/unittest/lib/unittest.dart (right):

https://codereview.chromium.org/208273009/diff/20001/pkg/unittest/lib/unittes...
pkg/unittest/lib/unittest.dart:107: /// There may be times when the number of
times a callback should be called is
On 2014/03/25 17:33:18, Siggi Cherem (dart-lang) wrote:
> On 2014/03/25 01:01:34, kevmoo wrote:
> > This paragraph is tough to understand. Should we just nuke it?
> 
> Sure, an alternative here would be to explain it differently, for example: 
> 
> ---
> If you need to block the test until one of a several callbacks is invoked, you
> can follow this pattern:
>    // test will block until notifyDone is invoked
>    var notifyDone = expectAsync(() {}); 
>    bool aCalled = false;
>    bool bCalled = false;
>    someApi.run(() { aCalled = true; notifyDone(); });
>    someOtherApi.run(() { aCalled = true; notifyDone(); });
>    expect(aCalled || bCalled, isTrue);
>    expect(aCalled && bCalled, isFalse);
> 
> ---
> We had this because people had a hard time coming up with this pattern before,
> so it was important to bring it up. Now that we have 'return Future', you
could
> also create a completer and mark it as done when you need it to, so maybe it's
> not as relevant anymore.

I guess we can ponder. This delta is an improvement. Always room to make it
better.

[kevmoo, 2014-03-25 19:44:09]

Committed patchset #3 manually as r34384 (presubmit successful).