Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/iterable_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.iterable_matchers;
 
 import 'core_matchers.dart';
 import 'description.dart';
 import 'interfaces.dart';
 import 'util.dart';
@@ skipping 60 matching lines @@
 
   bool matches(item, Map matchState) {
     return item.any((e) => _matcher.matches(e, matchState));
   }
 
   Description describe(Description description) =>
       description.add('some element ').addDescriptionOf(_matcher);
 }
 
 /// Returns a matcher which matches [Iterable]s that have the same
-/// length and the same elements as [expected], and in the same order.
-/// This is equivalent to equals but does not recurse.
-
+/// length and the same elements as [expected], in the same order.
+///
+/// This is equivalent to [equals] but does not recurse.
 Matcher orderedEquals(Iterable expected) => new _OrderedEquals(expected);
 
 class _OrderedEquals extends Matcher {
   final Iterable _expected;
   Matcher _matcher;
 
   _OrderedEquals(this._expected) {
     _matcher = equals(_expected, 1);
   }
 
   bool matches(item, Map matchState) =>
       (item is Iterable) && _matcher.matches(item, matchState);
 
   Description describe(Description description) =>
       description.add('equals ').addDescriptionOf(_expected).add(' ordered');
 
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) {
     if (item is !Iterable) {
       return mismatchDescription.add('is not an Iterable');
     } else {
       return _matcher.describeMismatch(item, mismatchDescription,
           matchState, verbose);
     }
   }
 }
 
-/// Returns a matcher which matches [Iterable]s that have the same
-/// length and the same elements as [expected], but not necessarily in
-/// the same order. Note that this is O(n^2) so should only be used on
-/// small objects.
+/// Returns a matcher which matches [Iterable]s that have the same length and
+/// the same elements as [expected], but not necessarily in the same order.
+///
+/// Note that this is O(n^2) so should only be used on small objects.
 Matcher unorderedEquals(Iterable expected) => new _UnorderedEquals(expected);
 
 class _UnorderedEquals extends _UnorderedMatches {
   final List _expectedValues;
 
   _UnorderedEquals(Iterable expected)
       : super(expected.map(equals)),
         _expectedValues = expected.toList();
 
   Description describe(Description description) =>
@@ skipping 77 matching lines @@
     description
       .add('matches ')
       .addAll('[', ', ', ']', _expected)
       .add(' unordered');
 
   Description describeMismatch(item, Description mismatchDescription,
                                Map matchState, bool verbose) =>
       mismatchDescription.add(_test(item));
 }
 
-/// A pairwise matcher for iterable. You can pass an arbitrary [comparator]
-/// function that takes an expected and actual argument which will be applied
-/// to each pair in order. [description]  should be a meaningful name for
-/// the comparator.
+/// A pairwise matcher for [Iterable]s.
+///
+/// The [comparator] function, taking an expected and an actual argument, and
+/// returning whether they match, will be applied to each pair in order.
+/// [description] should be a meaningful name for the comparator.
 Matcher pairwiseCompare(Iterable expected, bool comparator(a, b),
     String description) =>
         new _PairwiseCompare(expected, comparator, description);
 
 typedef bool _Comparator(a, b);
 
 class _PairwiseCompare extends _IterableMatcher {
   final Iterable _expected;
   final _Comparator _comparator;
   final String _description;
@@ skipping 30 matching lines @@
     } else {
       return mismatchDescription.
           add('has ').
           addDescriptionOf(matchState["actual"]).
           add(' which is not $_description ').
           addDescriptionOf(matchState["expected"]).
           add(' at index ${matchState["index"]}');
     }
   }
 }