Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/string_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.string_matchers;
 
 import 'interfaces.dart';
 
 /// Returns a matcher which matches if the match argument is a string and
 /// is equal to [value] when compared case-insensitively.
 Matcher equalsIgnoringCase(String value) => new _IsEqualIgnoringCase(value);
 
 class _IsEqualIgnoringCase extends _StringMatcher {
   final String _value;
   final String _matchValue;
 
   _IsEqualIgnoringCase(String value)
       : _value = value,
         _matchValue = value.toLowerCase();
 
   bool matches(item, Map matchState) =>
       item is String && _matchValue == item.toLowerCase();
 
   Description describe(Description description) =>
       description.addDescriptionOf(_value).add(' ignoring case');
 }
 
 /// Returns a matcher which matches if the match argument is a string and
-/// is equal to [value] when compared with all runs of whitespace
-/// collapsed to single spaces and leading and trailing whitespace removed.
+/// is equal to [value], ignoring whitespace.
 ///
-/// For example, `equalsIgnoringCase("hello world")` will match
-/// "hello   world", "  hello world" and "hello world  ".
-Matcher equalsIgnoringWhitespace(String string) =>
-    new _IsEqualIgnoringWhitespace(string);
+/// In this matcher, "ignoring whitespace" means comparing with all runs of
+/// whitespace collapsed to single space characters and leading and trailing
+/// whitespace removed.
+///
+/// For example, the following will all match successfully:
+///
+///     expect("hello   world", equalsIgnoringCase("hello world"));
+///     expect("  hello world", equalsIgnoringCase("hello world"));
+///     expect("hello world  ", equalsIgnoringCase("hello world"));

[Bob Nystrom, 2014/10/06 16:14:28]

A negative example might help here too, like "he llo world" or "helloworld".

[srawlins, 2014/10/06 16:19:35]

Done.

+Matcher equalsIgnoringWhitespace(String value) =>
+    new _IsEqualIgnoringWhitespace(value);
 
 class _IsEqualIgnoringWhitespace extends _StringMatcher {
   final String _value;
   final String _matchValue;
 
   _IsEqualIgnoringWhitespace(String value)
       : _value = value,
         _matchValue = collapseWhitespace(value);
 
   bool matches(item, Map matchState) =>
@@ skipping 72 matching lines @@
     }
     return true;
   }
 
   Description describe(Description description) =>
       description.addAll('a string containing ', ', ', ' in order',
                                                   _substrings);
 }
 
 /// Returns a matcher that matches if the match argument is a string and
-/// matches the regular expression given by [re]. [re] can be a [RegExp]
-/// instance or a [String]; in the latter case it will be used to create
-/// a RegExp instance.
+/// matches the regular expression given by [re].
+///
+/// [re] can be a [RegExp] instance or a [String]; in the latter case it will be
+/// used to create a RegExp instance.
 Matcher matches(re) => new _MatchesRegExp(re);
 
 class _MatchesRegExp extends _StringMatcher {
   RegExp _regexp;
 
   _MatchesRegExp(re) {
     if (re is String) {
       _regexp = new RegExp(re);
     } else if (re is RegExp) {
       _regexp = re;
@@ skipping 41 matching lines @@
     } else {
       result.write(character);
       skipSpace = false;
     }
   }
   return result.toString().trim();
 }
 
 bool _isWhitespace(String ch) =>
     ch == ' ' || ch == '\n' || ch == '\r' || ch == '\t';