Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/core_matchers.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.core_matchers;
 
 import 'description.dart';
 import 'interfaces.dart';
 import 'util.dart';
 
@@ skipping 371 matching lines @@
 class isInstanceOf<T> extends Matcher {
   final String _name;
   const isInstanceOf([name = 'specified type']) : this._name = name;
   bool matches(obj, Map matchState) => obj is T;
   // The description here is lame :-(
   Description describe(Description description) =>
       description.add('an instance of ${_name}');
 }
 
 /// A matcher that matches a function call against no exception.
+///
 /// The function will be called once. Any exceptions will be silently swallowed.
 /// The value passed to expect() should be a reference to the function.
 /// Note that the function cannot take arguments; to handle this
 /// a wrapper will have to be created.
 const Matcher returnsNormally = const _ReturnsNormally();
 
 class _ReturnsNormally extends Matcher {
   const _ReturnsNormally();
 
   bool matches(f, Map matchState) {
@@ skipping 93 matching lines @@
       // property; we use the same trick as in matches().
       if (item.length * item.length >= 0) {
         return mismatchDescription.add('has length of ').
             addDescriptionOf(item.length);
       }
     } catch (e) {}
     return mismatchDescription.add('has no length property');
   }
 }
 
-/// Returns a matcher that matches if the match argument contains
-/// the expected value. For [String]s this means substring matching;
+/// Returns a matcher that matches if the match argument contains the expected
+/// value.
+///
+/// For [String]s this means substring matching;
 /// for [Map]s it means the map has the key, and for [Iterable]s
-/// (including [Iterable]s) it means the iterable has a matching
-/// element. In the case of iterables, [expected] can itself be a
-/// matcher.
+/// it means the iterable has a matching element. In the case of iterables,
+/// [expected] can itself be a matcher.
 Matcher contains(expected) => new _Contains(expected);
 
 class _Contains extends Matcher {
   final _expected;
 
   const _Contains(this._expected);
 
   bool matches(item, Map matchState) {
     if (item is String) {
       return item.indexOf(_expected) >= 0;
@@ skipping 41 matching lines @@
       return _expected.containsKey(item);
     }
     return false;
   }
 
   Description describe(Description description) =>
       description.add('is in ').addDescriptionOf(_expected);
 }
 
 /// Returns a matcher that uses an arbitrary function that returns
-/// true or false for the actual value. For example:
+/// true or false for the actual value.
+///
+/// For example:
 ///
 ///     expect(v, predicate((x) => ((x % 2) == 0), "is even"))
 Matcher predicate(bool f(value), [String description = 'satisfies function']) =>
     new _Predicate(f, description);
 
 typedef bool _PredicateFunction(value);
 
 class _Predicate extends Matcher {
   final _PredicateFunction _matcher;
   final String _description;
@@ skipping 52 matching lines @@
         addDescriptionOf(matchState['feature']);
     var innerDescription = new StringDescription();
     _matcher.describeMismatch(matchState['feature'], innerDescription,
         matchState['state'], verbose);
     if (innerDescription.length > 0) {
       mismatchDescription.add(' which ').add(innerDescription.toString());
     }
     return mismatchDescription;
   }
 }