Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/expect.dart

 // Copyright (c) 2012, 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.
 
 library matcher.expect;
 
 import 'core_matchers.dart';
 import 'description.dart';
 import 'interfaces.dart';
 import 'util.dart';
@@ skipping 27 matching lines @@
 
 /// The ErrorFormatter type is used for functions that
 /// can be used to build up error reports upon [expect] failures.
 /// There is one built-in implementation ([defaultErrorFormatter])
 /// which is used by the default failure handler. If the failure handler
 /// is replaced it may be desirable to replace the [stringDescription]
 /// error formatter with another.
 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
 /// such exceptions. The [wrapAsync] property is a function that
 /// can wrap callbacks used by these Matchers so that they can be
 /// used safely. For example, the unittest library will set this
 /// 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
 /// [equals] matcher.
 ///
 /// If the assertion fails, then the default behavior is to throw a
 /// [TestFailure], but this behavior can be changed by calling
 /// [configureExpectFailureHandler] and providing an alternative handler that
 /// implements the [IFailureHandler] interface. It is also possible to
 /// pass a [failureHandler] to [expect] as a final parameter for fine-
@@ skipping 42 matching lines @@
   }
   void fail(String reason) {
     throw new TestFailure(reason);
   }
   void failMatch(actual, Matcher matcher, String reason,
       Map matchState, bool verbose) {
     fail(_assertErrorFormatter(actual, matcher, reason, matchState, verbose));
   }
 }
 
-/// 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.
 void configureExpectFailureHandler([FailureHandler handler = null]) {
   if (handler == null) {
     handler = new DefaultFailureHandler();
   }
   _assertFailureHandler = handler;
 }
 
@@ skipping 19 matching lines @@
 
   if (mismatchDescription.length > 0) {
     description.add('   Which: ${mismatchDescription}\n');
   }
   if (reason != null) {
     description.add(reason).add('\n');
   }
   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
 /// get a reference to the default formatter.
 ErrorFormatter configureExpectFormatter([ErrorFormatter formatter = null]) {
   if (formatter == null) {
     formatter = _defaultErrorFormatter;
   }
   return _assertErrorFormatter = formatter;
 }