Merge pull request #332 from google:clarify-container-matcher-docs

PiperOrigin-RevId: 587704605

Author: copybara-github

googletest/src/matchers/container_eq_matcher.rs

@@ -29,9 +29,14 @@ use std::marker::PhantomData;
 ///   Unexpected: [4]
 /// ```
 ///
-/// The type of `expected` must implement `IntoIterator` with an `Item` which
-/// implements `PartialEq`. If the container type is a `Vec`, then the expected
-/// type may be a slice of the same element type. For example:
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`] whose `Item` type implements
+/// [`PartialEq<ExpectedT>`], where `ExpectedT` is the element type of the
+/// expected value.
+///
+/// If the container type is a `Vec`, then the expected type may be a slice of
+/// the same element type. For example:
 ///
 /// ```
 /// # use googletest::prelude::*;

googletest/src/matchers/each_matcher.rs

@@ -19,14 +19,19 @@ use std::{fmt::Debug, marker::PhantomData};
 /// Matches a container all of whose elements are matched by the matcher
 /// `inner`.
 ///
-/// `T` can be any container such that `&T` implements `IntoIterator`.
+/// `T` can be any container such that `&T` implements `IntoIterator`. This
+/// includes `Vec`, arrays, and (dereferenced) slices.
 ///
 /// ```
 /// # use googletest::prelude::*;
 /// # use std::collections::HashSet;
 /// # fn should_pass_1() -> Result<()> {
 /// let value = vec![1, 2, 3];
 /// verify_that!(value, each(gt(0)))?;  // Passes
+/// let array_value = [1, 2, 3];
+/// verify_that!(array_value, each(gt(0)))?;  // Passes
+/// let slice_value = &[1, 2, 3];
+/// verify_that!(*slice_value, each(gt(0)))?;  // Passes
 /// #     Ok(())
 /// # }
 /// # fn should_fail() -> Result<()> {

googletest/src/matchers/elements_are_matcher.rs

@@ -28,8 +28,9 @@
 /// #    .unwrap();
 /// ```
 ///
-/// The actual value must be a container implementing [`IntoIterator`]. This
-/// includes standard containers, slices (when dereferenced) and arrays.
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`].
 ///
 /// ```
 /// # use googletest::prelude::*;

googletest/src/matchers/empty_matcher.rs

@@ -17,7 +17,9 @@ use std::{fmt::Debug, marker::PhantomData};
 
 /// Matches an empty container.
 ///
-/// `T` can be any container such that `&T` implements `IntoIterator`.
+/// `T` can be any container such that `&T` implements `IntoIterator`. This
+/// includes common containers such as `Vec` and
+/// [`HashSet`][std::collections::HashSet].
 ///
 /// ```
 /// # use googletest::prelude::*;

googletest/src/matchers/len_matcher.rs

@@ -19,7 +19,9 @@ use std::{fmt::Debug, marker::PhantomData};
 /// Matches a container whose number of elements matches `expected`.
 ///
 /// This matches against a container over which one can iterate. This includes
-/// the standard Rust containers, arrays, and (when dereferenced) slices.
+/// the standard Rust containers, arrays, and (when dereferenced) slices. More
+/// precisely, a shared borrow of the actual type must implement
+/// [`IntoIterator`].
 ///
 /// ```
 /// # use googletest::prelude::*;

googletest/src/matchers/pointwise_matcher.rs

@@ -79,8 +79,9 @@
 /// that all of the containers have the same size. This matcher does not check
 /// whether the sizes match.
 ///
-/// The actual value must be a container implementing [`IntoIterator`]. This
-/// includes standard containers, slices (when dereferenced) and arrays.
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`].
 ///
 /// ```
 /// # use googletest::prelude::*;

googletest/src/matchers/subset_of_matcher.rs

@@ -22,14 +22,17 @@ use std::{fmt::Debug, marker::PhantomData};
 /// comparison.
 ///
 /// `ActualT` and `ExpectedT` can each be any container a reference to which
-/// implements `IntoIterator`. They need not be the same container type.
+/// implements `IntoIterator`. This includes common containers such as `Vec`
+/// or arrays. They need not be the same container type.
 ///
 /// ```
 /// # use googletest::prelude::*;
 /// # use std::collections::HashSet;
 /// # fn should_pass_1() -> Result<()> {
 /// let value = vec![1, 2, 3];
 /// verify_that!(value, subset_of([1, 2, 3, 4]))?;  // Passes
+/// let array_value = [1, 2, 3];
+/// verify_that!(array_value, subset_of([1, 2, 3, 4]))?;  // Passes
 /// #     Ok(())
 /// # }
 /// # fn should_fail() -> Result<()> {

googletest/src/matchers/superset_of_matcher.rs

@@ -22,14 +22,17 @@ use std::{fmt::Debug, marker::PhantomData};
 /// comparison.
 ///
 /// `ActualT` and `ExpectedT` can each be any container a reference to which
-/// implements `IntoIterator`. They need not be the same container type.
+/// implements `IntoIterator`. This includes common containers such as `Vec`
+/// or arrays. They need not be the same container type.
 ///
 /// ```
 /// # use googletest::prelude::*;
 /// # use std::collections::HashSet;
 /// # fn should_pass_1() -> Result<()> {
 /// let value = vec![1, 2, 3];
 /// verify_that!(value, superset_of([1, 2]))?;  // Passes
+/// let array_value = [1, 2, 3];
+/// verify_that!(array_value, superset_of([1, 2]))?;  // Passes
 /// #     Ok(())
 /// # }
 /// # fn should_fail() -> Result<()> {

googletest/src/matchers/unordered_elements_are_matcher.rs

@@ -43,8 +43,9 @@
 /// # should_fail_3().unwrap_err();
 /// ```
 ///
-/// The actual value must be a container implementing [`IntoIterator`]. This
-/// includes standard containers, slices (when dereferenced) and arrays.
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`].
 ///
 /// This can also match against [`HashMap`][std::collections::HashMap] and
 /// similar collections. The arguments are a sequence of pairs of matchers
@@ -181,8 +182,9 @@ macro_rules! __unordered_elements_are {
 /// # should_fail_3().unwrap_err();
 /// ```
 ///
-/// The actual value must be a container implementing [`IntoIterator`]. This
-/// includes standard containers, slices (when dereferenced) and arrays.
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`].
 ///
 /// This can also match against [`HashMap`][std::collections::HashMap] and
 /// similar collections. The arguments are a sequence of pairs of matchers
@@ -287,8 +289,9 @@ macro_rules! __contains_each {
 /// # should_fail_3().unwrap_err();
 /// ```
 ///
-/// The actual value must be a container implementing [`IntoIterator`]. This
-/// includes standard containers, slices (when dereferenced) and arrays.
+/// The actual value must be a container such as a `Vec`, an array, or a
+/// dereferenced slice. More precisely, a shared borrow of the actual value must
+/// implement [`IntoIterator`].
 ///
 /// This can also match against [`HashMap`][std::collections::HashMap] and
 /// similar collections. The arguments are a sequence of pairs of matchers