Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/expect.dart

Index: pkg/matcher/lib/src/expect.dart
diff --git a/pkg/matcher/lib/src/expect.dart b/pkg/matcher/lib/src/expect.dart
index bd54747685403042ad7830864c949482ce78c9fc..1bfa36ef37298b92516e800c7e273dea1efa8de8 100644
--- a/pkg/matcher/lib/src/expect.dart
+++ b/pkg/matcher/lib/src/expect.dart
@@ -45,6 +45,8 @@ abstract class FailureHandler {
 typedef String ErrorFormatter(actual, Matcher matcher, String reason,
   Map matchState, bool verbose);
 
+/// This Function is used by certain Matchers to catch certain exceptions.
+///
 /// Some matchers, like those for Futures and exception testing,
 /// can fail in asynchronous sections, and throw exceptions.
 /// A user of this library will typically want to catch and handle
@@ -54,9 +56,10 @@ typedef String ErrorFormatter(actual, Matcher matcher, String reason,
 /// to be `expectAsync`. By default this is an identity function.
 Function wrapAsync = (Function f, [id]) => f;
 
-/// This is the main assertion function. It asserts that [actual]
-/// matches the [matcher]. [reason] is optional and is typically not
-/// supplied, as a reason is generated from the matcher; if [reason]
+/// Assert that [actual] matches [matcher].
+///
+/// This is the main assertion function. [reason] is optional and is typically
+/// not supplied, as a reason is generated from the matcher; if [reason]
 /// is included it is appended to the reason generated by the matcher.
 ///
 /// [matcher] can be a value in which case it will be wrapped in an
@@ -119,7 +122,8 @@ class DefaultFailureHandler implements FailureHandler {
   }
 }
 
-/// Changes or resets to the default the failure handler for expect()
+/// Changes the default failure handler for [expect].
+///
 /// [handler] is a reference to the new handler; if this is omitted
 /// or null then the failure handler is reset to the default, which
 /// throws [TestFailure]s on [expect] assertion failures.
@@ -159,7 +163,8 @@ String _defaultErrorFormatter(actual, Matcher matcher, String reason,
   return description.toString();
 }
 
-/// Changes or resets to default the failure message formatter for expect().
+/// Changes the failure message formatter for expect().
+///
 /// [formatter] is a reference to the new formatter; if this is omitted or
 /// null then the failure formatter is reset to the default. The new
 /// formatter is returned; this allows custom expect handlers to easily