Index: pkg/matcher/lib/src/expect.dart |
diff --git a/pkg/matcher/lib/src/expect.dart b/pkg/matcher/lib/src/expect.dart |
index 073ef34300b24116fd61506758bc6e5b6e3d2030..2994163385c4a85639625e489804cc4c1edfc8c6 100644 |
--- a/pkg/matcher/lib/src/expect.dart |
+++ b/pkg/matcher/lib/src/expect.dart |
@@ -2,13 +2,9 @@ |
// 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; |
+part of matcher; |
-import 'core_matchers.dart'; |
-import 'description.dart'; |
-import 'interfaces.dart'; |
- |
-/// The objects thrown by the default failure handler. |
+/** The objects thrown by the default failure handler. */ |
class TestFailure extends Error { |
final String message; |
@@ -17,7 +13,9 @@ class TestFailure extends Error { |
String toString() => message; |
} |
-/// Useful utility for nesting match states. |
+/** |
+ * Useful utility for nesting match states. |
+ */ |
void addStateInfo(Map matchState, Map values) { |
var innerState = new Map.from(matchState); |
@@ -26,33 +24,37 @@ void addStateInfo(Map matchState, Map values) { |
matchState.addAll(values); |
} |
-/// 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. |
+/** |
+ * 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] |
-/// 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- |
-/// grained control. |
-/// |
-/// In some cases extra diagnostic info can be produced on failure (for |
-/// example, stack traces on mismatched exceptions). To enable these, |
-/// [verbose] should be specified as true; |
+/** |
+ * 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] |
+ * 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- |
+ * grained control. |
+ * |
+ * In some cases extra diagnostic info can be produced on failure (for |
+ * example, stack traces on mismatched exceptions). To enable these, |
+ * [verbose] should be specified as true; |
+ */ |
void expect(actual, matcher, {String reason, FailureHandler failureHandler, |
bool verbose : false}) { |
matcher = wrapMatcher(matcher); |
@@ -81,10 +83,12 @@ void fail(String message, {FailureHandler failureHandler}) { |
failureHandler.fail(message); |
} |
-/// 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. |
+/** |
+ * 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. |
+ */ |
Matcher wrapMatcher(x) { |
if (x is Matcher) { |
return x; |
@@ -114,10 +118,12 @@ class DefaultFailureHandler implements FailureHandler { |
} |
} |
-/// Changes or resets to the default the 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. |
+/** |
+ * Changes or resets to the default the 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(); |
@@ -154,14 +160,17 @@ String _defaultErrorFormatter(actual, Matcher matcher, String reason, |
return description.toString(); |
} |
-/// Changes or resets to default 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. |
+/** |
+ * Changes or resets to default 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; |
} |
+ |