Adjusting matcher comments with one-line summaries
BUG= https://code.google.com/p/dart/issues/detail?id=21240
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//629113002
git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart/pkg/matcher@40938 260f80e4-7a28-3924-810f-c04153c831b5
diff --git a/lib/src/core_matchers.dart b/lib/src/core_matchers.dart
index 8de3a01..c3c996d 100644
--- a/lib/src/core_matchers.dart
+++ b/lib/src/core_matchers.dart
@@ -389,6 +389,7 @@
}
/// 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
@@ -502,12 +503,13 @@
}
}
-/// 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 {
@@ -569,7 +571,9 @@
}
/// 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']) =>
diff --git a/lib/src/expect.dart b/lib/src/expect.dart
index bd54747..1bfa36e 100644
--- a/lib/src/expect.dart
+++ b/lib/src/expect.dart
@@ -45,6 +45,8 @@
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 @@
/// 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 @@
}
}
-/// 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 @@
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
diff --git a/lib/src/future_matchers.dart b/lib/src/future_matchers.dart
index f1d7cb8..615b588 100644
--- a/lib/src/future_matchers.dart
+++ b/lib/src/future_matchers.dart
@@ -10,17 +10,20 @@
import 'interfaces.dart';
import 'util.dart';
-/// Matches a [Future] that completes successfully with a value. Note that this
-/// creates an asynchronous expectation. The call to `expect()` that includes
-/// this will return immediately and execution will continue. Later, when the
-/// future completes, the actual expectation will run.
+/// Matches a [Future] that completes successfully with a value.
+///
+/// Note that this creates an asynchronous expectation. The call to `expect()`
+/// that includes this will return immediately and execution will continue.
+/// Later, when the future completes, the actual expectation will run.
///
/// To test that a Future completes with an exception, you can use [throws] and
/// [throwsA].
final Matcher completes = const _Completes(null, '');
/// Matches a [Future] that completes succesfully with a value that matches
-/// [matcher]. Note that this creates an asynchronous expectation. The call to
+/// [matcher].
+///
+/// Note that this creates an asynchronous expectation. The call to
/// `expect()` that includes this will return immediately and execution will
/// continue. Later, when the future completes, the actual expectation will run.
///
diff --git a/lib/src/iterable_matchers.dart b/lib/src/iterable_matchers.dart
index eeea0ee..60ef32d 100644
--- a/lib/src/iterable_matchers.dart
+++ b/lib/src/iterable_matchers.dart
@@ -78,9 +78,9 @@
}
/// 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 {
@@ -108,10 +108,10 @@
}
}
-/// 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 {
@@ -209,10 +209,11 @@
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);
diff --git a/lib/src/numeric_matchers.dart b/lib/src/numeric_matchers.dart
index ae0b0ad..03134dd 100644
--- a/lib/src/numeric_matchers.dart
+++ b/lib/src/numeric_matchers.dart
@@ -111,7 +111,9 @@
}
/// Returns a matcher which matches if the match argument is within [delta]
-/// of some [value]; i.e. if the match argument is greater than
+/// of some [value].
+///
+/// In other words, this matches if the match argument is greater than
/// than or equal [value]-[delta] and less than or equal to [value]+[delta].
Matcher closeTo(num value, num delta) => new _IsCloseTo(value, delta);
diff --git a/lib/src/operator_matchers.dart b/lib/src/operator_matchers.dart
index a6d23c2..4661b7d 100644
--- a/lib/src/operator_matchers.dart
+++ b/lib/src/operator_matchers.dart
@@ -22,9 +22,10 @@
}
/// This returns a matcher that matches if all of the matchers passed as
-/// arguments (up to 7) match. Instead of passing the matchers separately
-/// they can be passed as a single List argument.
-/// Any argument that is not a matcher is implicitly wrapped in a
+/// arguments (up to 7) match.
+///
+/// Instead of passing the matchers separately they can be passed as a single
+/// List argument. Any argument that is not a matcher is implicitly wrapped in a
/// Matcher to check for equality.
Matcher allOf(arg0,
[arg1 = null,
@@ -63,8 +64,9 @@
description.addAll('(', ' and ', ')', _matchers);
}
-/// Matches if any of the given matchers evaluate to true. The
-/// arguments can be a set of matchers as separate parameters
+/// Matches if any of the given matchers evaluate to true.
+///
+/// The arguments can be a set of matchers as separate parameters
/// (up to 7), or a List of matchers.
///
/// The matchers are evaluated from left to right using short-circuit
@@ -72,7 +74,6 @@
///
/// Any argument that is not a matcher is implicitly wrapped in a
/// Matcher to check for equality.
-
Matcher anyOf(arg0,
[arg1 = null,
arg2 = null,
diff --git a/lib/src/string_matchers.dart b/lib/src/string_matchers.dart
index c498446..616a4b6 100644
--- a/lib/src/string_matchers.dart
+++ b/lib/src/string_matchers.dart
@@ -26,13 +26,24 @@
}
/// 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"));
+///
+/// The following will not match:
+///
+/// expect("helloworld", equalsIgnoringCase("hello world"));
+/// expect("he llo world", equalsIgnoringCase("hello world"));
+Matcher equalsIgnoringWhitespace(String value) =>
+ new _IsEqualIgnoringWhitespace(value);
class _IsEqualIgnoringWhitespace extends _StringMatcher {
final String _value;
@@ -125,9 +136,10 @@
}
/// 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 {
diff --git a/lib/src/util.dart b/lib/src/util.dart
index 08cba77..3ecc47c 100644
--- a/lib/src/util.dart
+++ b/lib/src/util.dart
@@ -15,7 +15,8 @@
matchState.addAll(values);
}
-/// Takes an argument and returns an equivalent matcher.
+/// Takes an argument and returns an equivalent [Matcher].
+///
/// If the argument is already a matcher this does nothing,
/// else if the argument is a function, it generates a predicate
/// function matcher, else it generates an equals matcher.
