Merge pull request #306 from google:mangled_macros

PiperOrigin-RevId: 566231920

Author: copybara-github

README.md

@@ -30,6 +30,10 @@ version 1.66 for the best developer experience.
 
 > :warning: The API is not fully stable and may still be changed until we
 > publish version 1.0.
+>
+> Moreover, any items or modules starting with `__` (double underscores) must
+> not be used directly. Those items or modules are only for internal uses and
+> their API may change without a major version update.
 
 ## Assertions and matchers
 

googletest/crate_docs.md

@@ -153,38 +153,48 @@ The following matchers are provided in GoogleTest Rust:
 | [`superset_of`]      | A container containing all elements of the argument.                     |
 | [`unordered_elements_are!`] | A container whose elements the arguments match, in any order.     |
 
+[`all!`]: matchers::all
+[`any!`]: matchers::any
 [`anything`]: matchers::anything
 [`approx_eq`]: matchers::approx_eq
 [`char_count`]: matchers::char_count
 [`container_eq`]: matchers::container_eq
 [`contains`]: matchers::contains
+[`contains_each!`]: matchers::contains_each
 [`contains_regex`]: matchers::contains_regex
 [`contains_substring`]: matchers::contains_substring
 [`displays_as`]: matchers::displays_as
 [`each`]: matchers::each
+[`elements_are!`]: matchers::elements_are
 [`empty`]: matchers::empty
 [`ends_with`]: matchers::ends_with
 [`eq`]: matchers::eq
 [`eq_deref_of`]: matchers::eq_deref_of
 [`err`]: matchers::err
+[`field!`]: matchers::field
 [`ge`]: matchers::ge
 [`gt`]: matchers::gt
 [`has_entry`]: matchers::has_entry
+[`is_contained_in!`]: matchers::is_contained_in
 [`is_nan`]: matchers::is_nan
 [`le`]: matchers::le
 [`len`]: matchers::len
 [`lt`]: matchers::lt
 [`matches_regex`]: matchers::matches_regex
+[`matches_pattern!`]: matchers::matches_pattern
 [`near`]: matchers::near
 [`none`]: matchers::none
 [`not`]: matchers::not
+[`pat!`]: matchers::pat
 [`ok`]: matchers::ok
 [`points_to`]: matchers::points_to
+[`pointwise!`]: matchers::pointwise
 [`predicate`]: matchers::predicate
 [`some`]: matchers::some
 [`starts_with`]: matchers::starts_with
 [`subset_of`]: matchers::subset_of
 [`superset_of`]: matchers::superset_of
+[`unordered_elements_are!`]: matchers::unordered_elements_are
 [`Deref`]: std::ops::Deref
 [`Display`]: std::fmt::Display
 [`HashMap`]: std::collections::HashMap

googletest/src/assertions.rs

@@ -123,15 +123,15 @@ macro_rules! verify_that {
     ($actual:expr, [$($expecteds:expr),+ $(,)?]) => {
         $crate::assertions::internal::check_matcher(
             &$actual,
-            $crate::elements_are![$($expecteds),+],
+            $crate::matchers::elements_are![$($expecteds),+],
             stringify!($actual),
             $crate::internal::source_location::SourceLocation::new(file!(), line!(), column!()),
         )
     };
     ($actual:expr, {$($expecteds:expr),+ $(,)?}) => {
         $crate::assertions::internal::check_matcher(
             &$actual,
-            $crate::unordered_elements_are![$($expecteds),+],
+            $crate::matchers::unordered_elements_are![$($expecteds),+],
             stringify!($actual),
             $crate::internal::source_location::SourceLocation::new(file!(), line!(), column!()),
         )

googletest/src/lib.rs

@@ -49,11 +49,6 @@ pub mod prelude {
     pub use super::Result;
     // Assert macros
     pub use super::{assert_that, expect_pred, expect_that, fail, verify_pred, verify_that};
-    // Matcher macros
-    pub use super::{
-        all, any, contains_each, elements_are, field, is_contained_in, matches_pattern, pat,
-        pointwise, property, unordered_elements_are,
-    };
 }
 
 pub use googletest_macro::test;

googletest/src/matchers/all_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matcher module.
 #![doc(hidden)]
 
 /// Matches a value which all of the given matchers match.
@@ -51,7 +51,8 @@
 ///
 /// Assertion failure messages are not guaranteed to be identical, however.
 #[macro_export]
-macro_rules! all {
+#[doc(hidden)]
+macro_rules! __all {
     ($($matcher:expr),* $(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::AllMatcher;
         AllMatcher::new([$(Box::new($matcher)),*])

googletest/src/matchers/any_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matchers module.
 #![doc(hidden)]
 
 /// Matches a value which at least one of the given matchers match.
@@ -53,7 +53,8 @@
 ///
 /// Assertion failure messages are not guaranteed to be identical, however.
 #[macro_export]
-macro_rules! any {
+#[doc(hidden)]
+macro_rules! __any {
     ($($matcher:expr),* $(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::AnyMatcher;
         AnyMatcher::new([$(Box::new($matcher)),*])

googletest/src/matchers/elements_are_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matchers module.
 #![doc(hidden)]
 
 /// Matches a container's elements to each matcher in order.
@@ -50,7 +50,7 @@
 ///
 /// Note: This behavior is only possible in [`verify_that!`] macros. In any
 /// other cases, it is still necessary to use the
-/// [`elements_are!`][crate::elements_are] macro.
+/// [`elements_are!`][crate::matchers::elements_are] macro.
 ///
 /// ```compile_fail
 /// # use googletest::prelude::*;
@@ -69,15 +69,17 @@
 /// match against an iterator, use [`Iterator::collect`] to build a [`Vec`].
 ///
 /// Do not use this with unordered containers, since that will lead to flaky
-/// tests. Use [`unordered_elements_are!`][crate::unordered_elements_are]
+/// tests. Use
+/// [`unordered_elements_are!`][crate::matchers::unordered_elements_are]
 /// instead.
 ///
 /// [`IntoIterator`]: std::iter::IntoIterator
 /// [`Iterator`]: std::iter::Iterator
 /// [`Iterator::collect`]: std::iter::Iterator::collect
 /// [`Vec`]: std::vec::Vec
 #[macro_export]
-macro_rules! elements_are {
+#[doc(hidden)]
+macro_rules! __elements_are {
     ($($matcher:expr),* $(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::ElementsAre;
         ElementsAre::new(vec![$(Box::new($matcher)),*])

googletest/src/matchers/field_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matchers module.
 #![doc(hidden)]
 
 /// Matches a structure or enum with a given field which is matched by a given
@@ -105,10 +105,11 @@
 /// # }
 /// ```
 ///
-/// See also the macro [`property`][crate::property] for an analogous mechanism
-/// to extract a datum by invoking a method.
+/// See also the macro [`property`][crate::matchers::property] for an analogous
+/// mechanism to extract a datum by invoking a method.
 #[macro_export]
-macro_rules! field {
+#[doc(hidden)]
+macro_rules! __field {
     ($($t:tt)*) => { $crate::field_internal!($($t)*) }
 }
 

googletest/src/matchers/matches_pattern.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matchers module.
 #![doc(hidden)]
 
 /// Matches a value according to a pattern of matchers.
@@ -91,7 +91,8 @@
 /// #     .unwrap();
 /// ```
 ///
-/// One can use the alias [`pat`][crate::pat] to make this less verbose:
+/// One can use the alias [`pat`][crate::matchers::pat] to make this less
+/// verbose:
 ///
 /// ```
 /// # use googletest::prelude::*;
@@ -246,7 +247,8 @@
 /// #    .unwrap();
 /// ```
 #[macro_export]
-macro_rules! matches_pattern {
+#[doc(hidden)]
+macro_rules! __matches_pattern {
     ($($t:tt)*) => { $crate::matches_pattern_internal!($($t)*) }
 }
 
@@ -587,13 +589,14 @@ macro_rules! matches_pattern_internal {
 
     ($first:tt $($rest:tt)*) => {{
         #[allow(unused)]
-        use $crate::{all, field, property};
+        use $crate::matchers::{all, field, property};
         $crate::matches_pattern_internal!([$first], $($rest)*)
     }};
 }
 
-/// An alias for [`matches_pattern`].
+/// An alias for [`matches_pattern`][crate::matchers::matches_pattern!].
 #[macro_export]
-macro_rules! pat {
+#[doc(hidden)]
+macro_rules! __pat {
     ($($t:tt)*) => { $crate::matches_pattern_internal!($($t)*) }
 }

googletest/src/matchers/mod.rs

@@ -88,12 +88,13 @@ pub use str_matcher::{
 pub use subset_of_matcher::subset_of;
 pub use superset_of_matcher::superset_of;
 
-// Reexport of macros.
-// TODO Consider hiding the matchers macro from the top-level, by either
-// mangling or move them to the macro crate.
+// Reexport and unmangle the macros.
+#[doc(inline)]
 pub use crate::{
-    all, any, contains_each, elements_are, field, is_contained_in, matches_pattern, pat, pointwise,
-    property, unordered_elements_are,
+    __all as all, __any as any, __contains_each as contains_each, __elements_are as elements_are,
+    __field as field, __is_contained_in as is_contained_in, __matches_pattern as matches_pattern,
+    __pat as pat, __pointwise as pointwise, __property as property,
+    __unordered_elements_are as unordered_elements_are,
 };
 
 // Types and functions used by macros matchers.

googletest/src/matchers/pointwise_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matcher module.
 #![doc(hidden)]
 
 /// Generates a matcher which matches a container each of whose elements match
@@ -115,7 +115,8 @@
 /// [`Pointwise`]: https://google.github.io/googletest/reference/matchers.html#container-matchers
 /// [`Vec`]: std::vec::Vec
 #[macro_export]
-macro_rules! pointwise {
+#[doc(hidden)]
+macro_rules! __pointwise {
     ($matcher:expr, $container:expr) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::PointwiseMatcher;
         PointwiseMatcher::new($container.into_iter().map($matcher).collect())

googletest/src/matchers/property_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matcher module.
 #![doc(hidden)]
 
 /// Matches an object which, upon calling the given method on it with the given
@@ -96,13 +96,14 @@
 /// #    .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
-/// than accessing a field.
+/// This macro is analogous to [`field`][crate::matchers::field], except that it
+/// extracts the datum to be matched from the given object by invoking a method
+/// rather than accessing a field.
 ///
 /// The list of arguments may optionally have a trailing comma.
 #[macro_export]
-macro_rules! property {
+#[doc(hidden)]
+macro_rules! __property {
     ($($t:tt)*) => { $crate::property_internal!($($t)*) }
 }
 

googletest/src/matchers/unordered_elements_are_matcher.rs

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 // There are no visible documentation elements in this module; the declarative
-// macro is documented at the top level.
+// macro is documented in the matchers module.
 #![doc(hidden)]
 
 /// Matches a container whose elements in any order have a 1:1 correspondence
@@ -73,7 +73,7 @@
 ///
 /// Note: This behavior is only possible in [`verify_that!`] macros. In any
 /// other cases, it is still necessary to use the
-/// [`unordered_elements_are!`][crate::unordered_elements_are] macro.
+/// [`unordered_elements_are!`][crate::matchers::unordered_elements_are] macro.
 ///
 /// ```compile_fail
 /// # use googletest::prelude::*;
@@ -115,7 +115,8 @@
 /// [`Iterator::collect`]: std::iter::Iterator::collect
 /// [`Vec`]: std::vec::Vec
 #[macro_export]
-macro_rules! unordered_elements_are {
+#[doc(hidden)]
+macro_rules! __unordered_elements_are {
     ($(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::{
             UnorderedElementsAreMatcher, Requirements
@@ -151,7 +152,9 @@ macro_rules! unordered_elements_are {
 /// additional elements that don't correspond to any matcher.
 ///
 /// Put another way, `contains_each!` matches if there is a subset of the actual
-/// container which [`unordered_elements_are`] would match.
+/// container which
+/// [`unordered_elements_are`][crate::matchers::unordered_elements_are] would
+/// match.
 ///
 /// ```
 /// # use googletest::prelude::*;
@@ -217,7 +220,8 @@ macro_rules! unordered_elements_are {
 /// [`Iterator::collect`]: std::iter::Iterator::collect
 /// [`Vec`]: std::vec::Vec
 #[macro_export]
-macro_rules! contains_each {
+#[doc(hidden)]
+macro_rules! __contains_each {
     ($(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::{
             UnorderedElementsAreMatcher, Requirements
@@ -255,7 +259,8 @@ macro_rules! contains_each {
 /// container.
 ///
 /// Put another way, `is_contained_in!` matches if there is a subset of the
-/// matchers which would match with [`unordered_elements_are`].
+/// matchers which would match with
+/// [`unordered_elements_are`][crate::matchers::unordered_elements_are].
 ///
 /// ```
 /// # use googletest::prelude::*;
@@ -323,7 +328,8 @@ macro_rules! contains_each {
 /// [`Iterator::collect`]: std::iter::Iterator::collect
 /// [`Vec`]: std::vec::Vec
 #[macro_export]
-macro_rules! is_contained_in {
+#[doc(hidden)]
+macro_rules! __is_contained_in {
     ($(,)?) => {{
         use $crate::matchers::__internal_unstable_do_not_depend_on_these::{
             UnorderedElementsAreMatcher, Requirements