Skip to content

Commit 6b1a9c0

Browse files
jacobsacopybara-github
authored andcommitted
matcher: improve the documentation for Matcher::describe.
I found the existing documentation a little confusing. It used the word "result" to refer to something that is only a polarity, not an actual result of the matcher, and lacked an example for the negative sense of the matcher. I've corrected both here, putting this in a form that would have been clearer to me as a user. PiperOrigin-RevId: 919484474
1 parent 7e06fc9 commit 6b1a9c0

1 file changed

Lines changed: 11 additions & 7 deletions

File tree

googletest/src/matcher.rs

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,9 @@ pub trait Matcher<ActualT: Debug + Copy>: MatcherBase {
4444
/// the `==` operator) to the value `actual`.
4545
fn matches(&self, actual: ActualT) -> MatcherResult;
4646

47-
/// Returns a description of `self` or a negative description if
48-
/// `matcher_result` is `NoMatch`.
47+
/// Returns a description of `self` according to the supplied matching
48+
/// sense: a positive description if `sense` is `Match`, and a negative
49+
/// description if it's `NoMatch`.
4950
///
5051
/// The function should print a verb phrase that describes the property a
5152
/// value matching, respectively not matching, this matcher should have.
@@ -68,16 +69,19 @@ pub trait Matcher<ActualT: Debug + Copy>: MatcherBase {
6869
/// [`some`][crate::matchers::some] implements `describe` as follows:
6970
///
7071
/// ```ignore
71-
/// fn describe(&self, matcher_result: MatcherResult) -> Description {
72-
/// match matcher_result {
72+
/// fn describe(&self, sense: MatcherResult) -> Description {
73+
/// match sense {
7374
/// MatcherResult::Match => {
7475
/// Description::new()
7576
/// .text("has a value which")
7677
/// .nested(self.inner.describe(MatcherResult::Match))
7778
/// // Inner matcher: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7879
/// }
79-
///
80-
/// MatcherResult::NoMatch => {...} // Similar to the above
80+
/// MatcherResult::NoMatch => {
81+
/// Description::new()
82+
/// .text("is None or has a value which")
83+
/// .nested(self.inner.describe(MatcherResult::NoMatch))
84+
/// }
8185
/// }
8286
/// }
8387
/// ```
@@ -89,7 +93,7 @@ pub trait Matcher<ActualT: Debug + Copy>: MatcherBase {
8993
/// output of `explain_match` is always used adjectivally to describe the
9094
/// actual value, while `describe` is used in contexts where a relative
9195
/// clause would not make sense.
92-
fn describe(&self, matcher_result: MatcherResult) -> Description;
96+
fn describe(&self, sense: MatcherResult) -> Description;
9397

9498
/// Prepares a [`String`] describing how the expected value
9599
/// encoded in this instance matches or does not match the given value

0 commit comments

Comments
 (0)