From 6b1a9c0fbd84accdabbcac904c6d542cb7c7ae79 Mon Sep 17 00:00:00 2001 From: Aaron Jacobs Date: Thu, 21 May 2026 23:55:06 -0700 Subject: [PATCH] `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 --- googletest/src/matcher.rs | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/googletest/src/matcher.rs b/googletest/src/matcher.rs index 861115ad..454af7a7 100644 --- a/googletest/src/matcher.rs +++ b/googletest/src/matcher.rs @@ -44,8 +44,9 @@ pub trait Matcher: MatcherBase { /// the `==` operator) to the value `actual`. fn matches(&self, actual: ActualT) -> MatcherResult; - /// Returns a description of `self` or a negative description if - /// `matcher_result` is `NoMatch`. + /// Returns a description of `self` according to the supplied matching + /// sense: a positive description if `sense` is `Match`, and a negative + /// description if it's `NoMatch`. /// /// The function should print a verb phrase that describes the property a /// value matching, respectively not matching, this matcher should have. @@ -68,16 +69,19 @@ pub trait Matcher: MatcherBase { /// [`some`][crate::matchers::some] implements `describe` as follows: /// /// ```ignore - /// fn describe(&self, matcher_result: MatcherResult) -> Description { - /// match matcher_result { + /// fn describe(&self, sense: MatcherResult) -> Description { + /// match sense { /// MatcherResult::Match => { /// Description::new() /// .text("has a value which") /// .nested(self.inner.describe(MatcherResult::Match)) /// // Inner matcher: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ /// } - /// - /// MatcherResult::NoMatch => {...} // Similar to the above + /// MatcherResult::NoMatch => { + /// Description::new() + /// .text("is None or has a value which") + /// .nested(self.inner.describe(MatcherResult::NoMatch)) + /// } /// } /// } /// ``` @@ -89,7 +93,7 @@ pub trait Matcher: MatcherBase { /// output of `explain_match` is always used adjectivally to describe the /// actual value, while `describe` is used in contexts where a relative /// clause would not make sense. - fn describe(&self, matcher_result: MatcherResult) -> Description; + fn describe(&self, sense: MatcherResult) -> Description; /// Prepares a [`String`] describing how the expected value /// encoded in this instance matches or does not match the given value