Document regex syntax for contains_regex and matches_regex.

This CL documents that the regex matchers use the standard Rust `regex` crate,
and clarifies the syntax they accept. It also adds a warning about using `(?m)`
with `matches_regex`.

PUBLIC: Document regex syntax for contains_regex and matches_regex.
PiperOrigin-RevId: 920782797

Author: ravidahiya-google

googletest/src/matchers/contains_regex_matcher.rs

@@ -44,6 +44,20 @@ use std::ops::Deref;
 /// # should_pass_2().unwrap();
 /// ```
 ///
+/// # Regular Expression Syntax
+///
+/// The regular expression syntax matches that of the [`regex` crate](https://docs.rs/regex).
+/// This is a linear-time regular expression engine which does not support lookarounds
+/// or backreferences.
+///
+/// To enable multi-line matching (where `^` and `$` match line boundaries instead of
+/// the start and end of the entire input), prefix the pattern with `(?m)`.
+///
+/// For details on the supported syntax, see the
+/// [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).
+///
+/// # Panics
+///
 /// Panics if the given `pattern` is not a syntactically valid regular
 /// expression.
 #[track_caller]

googletest/src/matchers/matches_regex_matcher.rs

@@ -52,6 +52,33 @@ use std::ops::Deref;
 /// # should_pass_2().unwrap();
 /// ```
 ///
+/// # Regular Expression Syntax
+///
+/// The regular expression syntax matches that of the [`regex` crate](https://docs.rs/regex).
+/// This is a linear-time regular expression engine which does not support lookarounds
+/// or backreferences.
+///
+/// For details on the supported syntax, see the
+/// [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).
+///
+/// Note that `matches_regex` automatically wraps the pattern with `^` and `$`
+/// to ensure it matches the entire string.
+///
+/// ## Multi-line matching
+///
+/// If you want to match a multi-line string where `.` matches newlines, use the
+/// `(?s)` flag (e.g., `(?s)begin.*end`).
+///
+/// Avoid using the `(?m)` flag (multi-line mode) with `matches_regex`, as it
+/// redefines `^` and `$` to match line boundaries. Because `matches_regex`
+/// wraps your pattern in `^...$` and uses `is_match` internally, enabling
+/// `(?m)` will cause the matcher to succeed if *any* single line matches the
+/// pattern, rather than requiring the entire string to match. If you want to
+/// match a pattern against individual lines of a multi-line string, use
+/// [`contains_regex`][crate::matchers::contains_regex] with `(?m)` instead.
+///
+/// # Panics
+///
 /// Panics if the given `pattern` is not a syntactically valid regular
 /// expression.
 // N.B. This returns the concrete type rather than an impl Matcher so that it