Index: pkg/matcher/lib/src/interfaces.dart |
diff --git a/pkg/matcher/lib/src/interfaces.dart b/pkg/matcher/lib/src/interfaces.dart |
index 9fc110781fe8d6260821b5c9abc83be07ee50ed0..71079e5e3b2475b6394d6eb30c1764f9ed7048a6 100644 |
--- a/pkg/matcher/lib/src/interfaces.dart |
+++ b/pkg/matcher/lib/src/interfaces.dart |
@@ -7,80 +7,97 @@ library matcher.interfaces; |
// To decouple the reporting of errors, and allow for extensibility of |
// matchers, we make use of some interfaces. |
-/// The ErrorFormatter type is used for functions that |
-/// can be used to build up error reports upon [expect] failures. |
-/// There is one built-in implementation ([defaultErrorFormatter]) |
-/// which is used by the default failure handler. If the failure handler |
-/// is replaced it may be desirable to replace the [stringDescription] |
-/// error formatter with another. |
+/** |
+ * The ErrorFormatter type is used for functions that |
+ * can be used to build up error reports upon [expect] failures. |
+ * There is one built-in implementation ([defaultErrorFormatter]) |
+ * which is used by the default failure handler. If the failure handler |
+ * is replaced it may be desirable to replace the [stringDescription] |
+ * error formatter with another. |
+ */ |
typedef String ErrorFormatter(actual, Matcher matcher, String reason, |
Map matchState, bool verbose); |
-/// Matchers build up their error messages by appending to |
-/// Description objects. This interface is implemented by |
-/// StringDescription. This interface is unlikely to need |
-/// other implementations, but could be useful to replace in |
-/// some cases - e.g. language conversion. |
+/** |
+ * Matchers build up their error messages by appending to |
+ * Description objects. This interface is implemented by |
+ * StringDescription. This interface is unlikely to need |
+ * other implementations, but could be useful to replace in |
+ * some cases - e.g. language conversion. |
+ */ |
abstract class Description { |
int get length; |
- /// Change the value of the description. |
+ /** Change the value of the description. */ |
Description replace(String text); |
- /// This is used to add arbitrary text to the description. |
+ /** This is used to add arbitrary text to the description. */ |
Description add(String text); |
- /// This is used to add a meaningful description of a value. |
+ /** This is used to add a meaningful description of a value. */ |
Description addDescriptionOf(value); |
- /// This is used to add a description of an [Iterable] [list], |
- /// with appropriate [start] and [end] markers and inter-element [separator]. |
+ /** |
+ * This is used to add a description of an [Iterable] [list], |
+ * with appropriate [start] and [end] markers and inter-element [separator]. |
+ */ |
Description addAll(String start, String separator, String end, Iterable list); |
} |
-/// [expect] Matchers must implement/extend the Matcher class. |
-/// The base Matcher class has a generic implementation of [describeMismatch] |
-/// so this does not need to be provided unless a more clear description is |
-/// required. The other two methods ([matches] and [describe]) |
-/// must always be provided as they are highly matcher-specific. |
+/** |
+ * [expect] Matchers must implement/extend the Matcher class. |
+ * The base Matcher class has a generic implementation of [describeMismatch] |
+ * so this does not need to be provided unless a more clear description is |
+ * required. The other two methods ([matches] and [describe]) |
+ * must always be provided as they are highly matcher-specific. |
+ */ |
abstract class Matcher { |
const Matcher(); |
- /// This does the matching of the actual vs expected values. |
- /// [item] is the actual value. [matchState] can be supplied |
- /// and may be used to add details about the mismatch that are too |
- /// costly to determine in [describeMismatch]. |
+ /** |
+ * This does the matching of the actual vs expected values. |
+ * [item] is the actual value. [matchState] can be supplied |
+ * and may be used to add details about the mismatch that are too |
+ * costly to determine in [describeMismatch]. |
+ */ |
bool matches(item, Map matchState); |
- /// This builds a textual description of the matcher. |
+ /** This builds a textual description of the matcher. */ |
Description describe(Description description); |
- /// This builds a textual description of a specific mismatch. [item] |
- /// is the value that was tested by [matches]; [matchState] is |
- /// the [Map] that was passed to and supplemented by [matches] |
- /// with additional information about the mismact, and [mismatchDescription] |
- /// is the [Description] that is being built to decribe the mismatch. |
- /// A few matchers make use of the [verbose] flag to provide detailed |
- /// information that is not typically included but can be of help in |
- /// diagnosing failures, such as stack traces. |
+ /** |
+ * This builds a textual description of a specific mismatch. [item] |
+ * is the value that was tested by [matches]; [matchState] is |
+ * the [Map] that was passed to and supplemented by [matches] |
+ * with additional information about the mismact, and [mismatchDescription] |
+ * is the [Description] that is being built to decribe the mismatch. |
+ * A few matchers make use of the [verbose] flag to provide detailed |
+ * information that is not typically included but can be of help in |
+ * diagnosing failures, such as stack traces. |
+ */ |
Description describeMismatch(item, Description mismatchDescription, |
Map matchState, bool verbose) => mismatchDescription; |
} |
-/// Failed matches are reported using a default IFailureHandler. |
-/// The default implementation simply throws [TestFailure]s; |
-/// this can be replaced by some other implementation of |
-/// IFailureHandler by calling configureExpectHandler. |
+/** |
+ * Failed matches are reported using a default IFailureHandler. |
+ * The default implementation simply throws [TestFailure]s; |
+ * this can be replaced by some other implementation of |
+ * IFailureHandler by calling configureExpectHandler. |
+ */ |
abstract class FailureHandler { |
- /// This handles failures given a textual decription |
+ /** This handles failures given a textual decription */ |
void fail(String reason); |
- /// This handles failures given the actual [value], the [matcher] |
- /// the [reason] (argument from [expect]), some additonal [matchState] |
- /// generated by the [matcher], and a verbose flag which controls in |
- /// some cases how much [matchState] information is used. It will use |
- /// these to create a detailed error message (typically by calling |
- /// an [ErrorFormatter]) and then call [fail] with this message. |
+ /** |
+ * This handles failures given the actual [value], the [matcher] |
+ * the [reason] (argument from [expect]), some additonal [matchState] |
+ * generated by the [matcher], and a verbose flag which controls in |
+ * some cases how much [matchState] information is used. It will use |
+ * these to create a detailed error message (typically by calling |
+ * an [ErrorFormatter]) and then call [fail] with this message. |
+ */ |
void failMatch(actual, Matcher matcher, String reason, |
Map matchState, bool verbose); |
} |
+ |