Improve docs for async matchers (#1225)
Closes #1224
Remove the last sentence which references `AsyncMatcher` by name since
that is an implementation detail, and the reference to `expect` was
confusing and contradicted the paragraph above.
Rephrase the paragraph about asynchronous matching to reference both
`expect` and `expectLater`. Expand on "the actual expectation" by
referencing the `matcher` argument explicitly.
diff --git a/pkgs/test_api/CHANGELOG.md b/pkgs/test_api/CHANGELOG.md
index ddbb2db..b011ca1 100644
--- a/pkgs/test_api/CHANGELOG.md
+++ b/pkgs/test_api/CHANGELOG.md
@@ -1,3 +1,5 @@
+## 0.2.16-dev
+
## 0.2.15
* Cancel any StreamQueue that is created as a part of a stream matcher once it
diff --git a/pkgs/test_api/lib/src/frontend/future_matchers.dart b/pkgs/test_api/lib/src/frontend/future_matchers.dart
index 8117395..c456c30 100644
--- a/pkgs/test_api/lib/src/frontend/future_matchers.dart
+++ b/pkgs/test_api/lib/src/frontend/future_matchers.dart
@@ -11,31 +11,29 @@
import 'expect.dart';
import 'utils.dart';
-/// Matches a [Future] that completes successfully with a value.
+/// Matches a [Future] that completes successfully with any value.
///
-/// Note that this creates an asynchronous expectation. The call to `expect()`
-/// that includes this will return immediately and execution will continue.
-/// Later, when the future completes, the actual expectation will run.
+/// This creates an asynchronous expectation. The call to [expect] will return
+/// immediately and execution will continue. Later, when the future completes,
+/// the expectation against [matcher] will run. To wait for the future to
+/// complete and the expectation to run use [expectLater] and wait on the
+/// returned future.
///
/// To test that a Future completes with an exception, you can use [throws] and
/// [throwsA].
-///
-/// This returns an [AsyncMatcher], so [expect] won't complete until the matched
-/// future does.
final Matcher completes = const _Completes(null);
/// Matches a [Future] that completes succesfully with a value that matches
/// [matcher].
///
-/// Note that this creates an asynchronous expectation. The call to
-/// `expect()` that includes this will return immediately and execution will
-/// continue. Later, when the future completes, the actual expectation will run.
+/// This creates an asynchronous expectation. The call to [expect] will return
+/// immediately and execution will continue. Later, when the future completes,
+/// the expectation against [matcher] will run. To wait for the future to
+/// complete and the expectation to run use [expectLater] and wait on the
+/// returned future.
///
/// To test that a Future completes with an exception, you can use [throws] and
/// [throwsA].
-///
-/// This returns an [AsyncMatcher], so [expect] won't complete until the matched
-/// future does.
Matcher completion(matcher, [@deprecated String description]) =>
_Completes(wrapMatcher(matcher));
diff --git a/pkgs/test_api/pubspec.yaml b/pkgs/test_api/pubspec.yaml
index bd724e7..e988f87 100644
--- a/pkgs/test_api/pubspec.yaml
+++ b/pkgs/test_api/pubspec.yaml
@@ -1,5 +1,5 @@
name: test_api
-version: 0.2.15
+version: 0.2.16-dev
description: A library for writing Dart tests.
homepage: https://github.com/dart-lang/test/blob/master/pkgs/test_api
