From 30825555883afb5e8d63ae43d1261f389097939a Mon Sep 17 00:00:00 2001
From: Ravi Kumar <ravidahiya@google.com>
Date: Sun, 24 May 2026 23:07:46 -0700
Subject: [PATCH] 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
---
 .../src/matchers/contains_regex_matcher.rs    | 15 +++++++++++
 .../src/matchers/matches_regex_matcher.rs     | 27 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/googletest/src/matchers/contains_regex_matcher.rs b/googletest/src/matchers/contains_regex_matcher.rs
index 473d94af..5c3525b2 100644
--- a/googletest/src/matchers/contains_regex_matcher.rs
+++ b/googletest/src/matchers/contains_regex_matcher.rs
@@ -44,6 +44,21 @@ 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]
diff --git a/googletest/src/matchers/matches_regex_matcher.rs b/googletest/src/matchers/matches_regex_matcher.rs
index 10f190af..bef76059 100644
--- a/googletest/src/matchers/matches_regex_matcher.rs
+++ b/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