Merge pull request #182 from google:adjust-property-matcher-docs

PiperOrigin-RevId: 528740813

Author: copybara-github

googletest/src/matchers/matches_pattern.rs

@@ -44,7 +44,8 @@
 /// #     .unwrap();
 /// ```
 ///
-/// It is not required to include all named fields in the specification:
+/// It is not required to include all named fields in the specification. Omitted
+/// fields have no effect on the output of the matcher.
 ///
 /// ```
 /// # use googletest::{matchers::starts_with, matches_pattern, verify_that};
@@ -136,6 +137,11 @@
 /// #     .unwrap();
 /// ```
 ///
+/// **Important**: The method should be pure function with a deterministic
+/// output and no side effects. In particular, in the event of an assertion
+/// failure, it will be invoked a second time, with the assertion failure output
+/// reflecting the *second* invocation.
+///
 /// These may also include extra parameters you pass in:
 ///
 /// ```
@@ -176,9 +182,6 @@
 /// #    .unwrap();
 /// ```
 ///
-/// > Note: At the moment, this does not work properly with methods returning
-/// > string references or slices.
-///
 /// One can also match tuple structs with up to 10 fields. In this case, all
 /// fields must have matchers:
 ///
@@ -217,14 +220,30 @@
 /// # should_fail().unwrap_err();
 /// ```
 ///
-/// It is perfectly okay to omit fields from a pattern with named fields. The
-/// values of omitted fields then have no effect on the output of the matcher.
-///
 /// This macro does not support plain (non-struct) tuples. Use the macro
 /// [`tuple`] for that purpose.
 ///
 /// Trailing commas are allowed (but not required) in both ordinary and tuple
 /// structs.
+///
+/// Unfortunately, this matcher does *not* work with methods returning string slices:
+///
+/// ```compile_fail
+/// # use googletest::{matchers::eq, property, verify_that};
+/// # #[derive(Debug)]
+/// pub struct MyStruct {
+///     a_string: String,
+/// }
+/// impl MyStruct {
+///     pub fn get_a_string(&self) -> &str { &self.a_string }
+/// }
+///
+/// let value = MyStruct { a_string: "A string".into() };
+/// verify_that!(value, matches_pattern!( MyStruct {
+///     get_a_string(): eq("A string"),   // Does not compile
+/// }))
+/// #    .unwrap();
+/// ```
 #[macro_export]
 macro_rules! matches_pattern {
     ($($t:tt)*) => { $crate::matches_pattern_internal!($($t)*) }

googletest/src/matchers/property_matcher.rs

@@ -42,6 +42,11 @@ use googletest::*;
 /// #    .unwrap();
 /// ```
 ///
+/// **Important**: The method should be pure function with a deterministic
+/// output and no side effects. In particular, in the event of an assertion
+/// failure, it will be invoked a second time, with the assertion failure output
+/// reflecting the *second* invocation.
+///
 /// If the method returns a *reference*, then it must be preceded by the keyword
 /// `ref`:
 ///
@@ -60,9 +65,6 @@ use googletest::*;
 /// #    .unwrap();
 /// ```
 ///
-/// > Note: At the moment, this does not work properly with methods returning
-/// > string references or slices.
-///
 /// The method may also take additional arguments:
 ///
 /// ```
@@ -80,10 +82,22 @@ use googletest::*;
 /// #    .unwrap();
 /// ```
 ///
-/// > **Note**: The method should be pure function with a deterministic output
-/// > and no side effects. In particular, in the event of an assertion failure,
-/// > it will be invoked a second time, with the assertion failure output
-/// > reflecting the *second* invocation.
+/// Unfortunately, this matcher does *not* work with methods returning string slices:
+///
+/// ```compile_fail
+/// # use googletest::{matchers::eq, property, verify_that};
+/// #[derive(Debug)]
+/// pub struct MyStruct {
+///     a_string: String,
+/// }
+/// impl MyStruct {
+///     pub fn get_a_string(&self) -> &str { &self.a_string }
+/// }
+///
+/// let value = MyStruct { a_string: "A string".into() };
+/// verify_that!(value, property!(ref MyStruct.get_a_string(), eq("A string"))) // Does not compile
+/// #    .unwrap();
+/// ```
 ///
 /// This macro is analogous to [`field`][crate::field], except that it extracts
 /// the datum to be matched from the given object by invoking a method rather

googletest/tests/property_matcher_test.rs

@@ -95,6 +95,21 @@ fn matches_struct_with_matching_string_reference_property() -> Result<()> {
     verify_that!(value, property!(ref StructWithString.get_property_ref(), eq("Something")))
 }
 
+#[google_test]
+fn matches_struct_with_matching_slice_property() -> Result<()> {
+    #[derive(Debug)]
+    struct StructWithVec {
+        property: Vec<u32>,
+    }
+    impl StructWithVec {
+        fn get_property_ref(&self) -> &[u32] {
+            &self.property
+        }
+    }
+    let value = StructWithVec { property: vec![1, 2, 3] };
+    verify_that!(value, property!(ref StructWithVec.get_property_ref(), eq([1, 2, 3])))
+}
+
 #[google_test]
 fn matches_struct_with_matching_property_ref_with_parameters() -> Result<()> {
     let value = SomeStruct { a_property: 10 };