Add extra documentation regarding the usage of the omitted matchers.

Author: bjacotg

googletest/src/matchers/elements_are_matcher.rs

@@ -40,13 +40,28 @@
 /// ```
 ///
 /// This can also be omitted in [`verify_that!`] macros and replaced with square brackets.
-/// 
+///
 /// ```
 /// # use googletest::prelude::*;
 ///  verify_that!(vec![1, 2], [eq(1), eq(2)])
 /// #     .unwrap();
 /// ```
-/// 
+///
+/// Note: This behavior is only possible in [`verify_that!`] macros. In any other cases, it is still necessary to use the [`elements_are!`] macro.
+///
+/// ```compile_fail
+/// # use googletest::prelude::*;
+/// verify_that!(vec![vec![1,2], vec![3]], [[eq(1), eq(2)], [eq(3)]])
+/// # .unwrap();
+/// ```
+///
+/// Prefer:
+/// ```
+/// # use googletest::prelude::*;
+/// verify_that!(vec![vec![1,2], vec![3]], [elements_are![eq(1), eq(2)], elements_are![eq(3)]])
+/// # .unwrap();
+/// ```
+///
 /// This matcher does not support matching directly against an [`Iterator`]. To
 /// match against an iterator, use [`Iterator::collect`] to build a [`Vec`].
 ///

googletest/src/matchers/unordered_elements_are_matcher.rs

@@ -62,13 +62,30 @@
 /// ```
 ///
 /// This can also be omitted in [`verify_that!`] macros and replaced with curly brackets.
-/// 
+///
 /// ```
 /// # use googletest::prelude::*;
 ///  verify_that!(vec![1, 2], {eq(2), eq(1)})
 /// #     .unwrap();
 /// ```
-/// 
+///
+/// Note: This behavior is only possible in [`verify_that!`] macros. In any other cases, it is still necessary
+/// to use the [`unordered_elements_are!`] macro.
+///
+/// ```compile_fail
+/// # use googletest::prelude::*;
+/// verify_that!(vec![vec![1,2], vec![3]], {{eq(2), eq(1)}, {eq(3)}})
+/// # .unwrap();
+/// ```
+///
+/// Prefer:
+/// ```
+/// # use googletest::prelude::*;
+/// verify_that!(vec![vec![1,2], vec![3]],
+///   {unordered_elements_are![eq(2), eq(1)], unordered_elements_are![eq(3)]})
+/// # .unwrap();
+/// ```
+///
 /// This matcher does not support matching directly against an [`Iterator`]. To
 /// match against an iterator, use [`Iterator::collect`] to build a [`Vec`].
 ///

googletest/tests/elements_are_matcher_test.rs

@@ -119,8 +119,7 @@ fn elements_are_works_when_matcher_is_created_in_subroutine() -> Result<()> {
     verify_that!(vec![1], create_matcher())
 }
 
-
 #[test]
 fn elements_are_implicitly_called() -> Result<()> {
-    verify_that!(vec![1,2,3], [eq(1), eq(2), eq(3)])
+    verify_that!(vec![1, 2, 3], [eq(1), eq(2), eq(3)])
 }