Backport missing Regex constructor remarks and examples

src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.cs

@@ -82,6 +82,26 @@ protected Regex()
         /// Initializes a new instance of the <see cref="Regex" /> class for the specified regular expression.
         /// </summary>
         /// <param name="pattern">The regular expression pattern to match.</param>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match.
+        /// For more information about regular expressions, see [Regular Expression Language - Quick Reference](https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference).
+        ///
+        /// Calling the <xref:System.Text.RegularExpressions.Regex.%23ctor(System.String)> constructor is equivalent to calling the
+        /// <xref:System.Text.RegularExpressions.Regex.%23ctor(System.String,System.Text.RegularExpressions.RegexOptions)> constructor with a value of
+        /// <xref:System.Text.RegularExpressions.RegexOptions.None> for the `options` argument.
+        ///
+        /// A <xref:System.Text.RegularExpressions.Regex> object is immutable, which means that it can be used only for the match pattern you define when you create it.
+        /// However, it can be used any number of times without being recompiled.
+        ///
+        /// This constructor creates a case-sensitive regular expression. For a case-insensitive match, use the
+        /// <xref:System.Text.RegularExpressions.Regex.%23ctor(System.String,System.Text.RegularExpressions.RegexOptions)?displayProperty=nameWithType> constructor.
+        ///
+        /// ## Examples
+        ///
+        /// The following example uses this constructor to create a regular expression that matches words beginning with the letters "a" or "t".
+        ///
+        /// [!code-csharp[](../../../../tests/FunctionalTests/Regex.Examples.cs#RegexCtorString)]
+        /// ]]></format></remarks>
         /// <exception cref="ArgumentException">A regular expression parsing error occurred.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="pattern" /> is <see langword="null" />.</exception>
         public Regex([StringSyntax(StringSyntaxAttribute.Regex)] string pattern) :
@@ -95,6 +115,19 @@ public Regex([StringSyntax(StringSyntaxAttribute.Regex)] string pattern) :
         /// </summary>
         /// <param name="pattern">The regular expression pattern to match.</param>
         /// <param name="options">A bitwise combination of the enumeration values that modify the regular expression.</param>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match.
+        /// For more information about regular expressions, see [Regular Expression Language - Quick Reference](https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference).
+        ///
+        /// A <xref:System.Text.RegularExpressions.Regex> object is immutable, which means that it can be used only for the match parameters you define when you create it.
+        /// However, it can be used any number of times without being recompiled.
+        ///
+        /// ## Examples
+        ///
+        /// The following example uses this constructor to create a case-insensitive regular expression that matches words beginning with the letters "a" or "t".
+        ///
+        /// [!code-csharp[](../../../../tests/FunctionalTests/Regex.Examples.cs#RegexCtorStringOptions)]
+        /// ]]></format></remarks>
         /// <exception cref="ArgumentException">A regular expression parsing error occurred.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="pattern" /> is <see langword="null" />.</exception>
         /// <exception cref="ArgumentOutOfRangeException">
@@ -115,6 +148,39 @@ public Regex([StringSyntax(StringSyntaxAttribute.Regex, nameof(options))] string
         /// <param name="matchTimeout">
         /// A time-out interval, or <see cref="InfiniteMatchTimeout" /> to indicate that the method should not time out.
         /// </param>
+        /// <remarks><format type="text/markdown"><![CDATA[
+        /// The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match.
+        /// For more information about regular expressions, see [Regular Expression Language - Quick Reference](https://learn.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference).
+        ///
+        /// A <xref:System.Text.RegularExpressions.Regex> object is immutable, which means that it can be used only for the match pattern you define when you create it.
+        /// However, it can be used any number of times without being recompiled.
+        ///
+        /// The `matchTimeout` parameter specifies how long a pattern-matching method should try to find a match before it times out.
+        /// If no match is found in that time interval, the pattern-matching method throws a <xref:System.Text.RegularExpressions.RegexMatchTimeoutException>.
+        /// The instance pattern-matching methods that observe the `matchTimeout` interval include:
+        ///
+        /// - <xref:System.Text.RegularExpressions.Regex.IsMatch*>
+        /// - <xref:System.Text.RegularExpressions.Regex.Match*>
+        /// - <xref:System.Text.RegularExpressions.Regex.Matches*>
+        /// - <xref:System.Text.RegularExpressions.Regex.Replace*>
+        /// - <xref:System.Text.RegularExpressions.Regex.Split*>
+        /// - <xref:System.Text.RegularExpressions.Match.NextMatch*?displayProperty=nameWithType>
+        ///
+        /// Setting a time-out interval can help prevent regular expressions that rely on excessive backtracking from appearing to stop responding
+        /// when they process input that contains near matches. For more information, see
+        /// [Best practices for regular expressions in .NET](https://learn.microsoft.com/dotnet/standard/base-types/best-practices-regex) and
+        /// [Backtracking in regular expressions](https://learn.microsoft.com/dotnet/standard/base-types/backtracking-in-regular-expressions).
+        /// When choosing a time-out interval, consider the following factors:
+        ///
+        /// - The length and complexity of the regular expression pattern.
+        /// - The expected machine load.
+        ///
+        /// ## Examples
+        ///
+        /// The following example creates a <xref:System.Text.RegularExpressions.Regex> object with a very short initial time-out and retries with a larger one if a timeout occurs.
+        ///
+        /// [!code-csharp[](../../../../tests/FunctionalTests/Regex.Examples.cs#RegexCtorStringOptionsMatchTimeout)]
+        /// ]]></format></remarks>
         /// <exception cref="ArgumentException">A regular expression parsing error occurred.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="pattern" /> is <see langword="null" />.</exception>
         /// <exception cref="ArgumentOutOfRangeException">

src/libraries/System.Text.RegularExpressions/tests/FunctionalTests/Regex.Examples.cs

@@ -28,4 +28,88 @@ public static void MatchZipCode()
             Assert.Equal("98052", match.Value);
         }
     }
+
+    public class RegexConstructorExamples
+    {
+        [Fact]
+        public static void ConstructorWithPattern()
+        {
+            #region RegexCtorString
+            string pattern = @"\b[at]\w+\b";
+            string input = "The archive was trimmed and tagged.";
+            MatchCollection matches = new Regex(pattern).Matches(input);
+            foreach (Match match in matches)
+                Console.WriteLine(match.Value);
+
+            // This code prints the following output:
+            //
+            // archive
+            // trimmed
+            // and
+            // tagged
+            #endregion
+
+            Assert.Equal(4, matches.Count);
+            Assert.Equal("archive", matches[0].Value);
+            Assert.Equal("trimmed", matches[1].Value);
+            Assert.Equal("and", matches[2].Value);
+            Assert.Equal("tagged", matches[3].Value);
+        }
+
+        [Fact]
+        public static void ConstructorWithPatternAndOptions()
+        {
+            #region RegexCtorStringOptions
+            string pattern = @"\b[at]\w+\b";
+            string input = "The archive was trimmed and tagged.";
+            MatchCollection matches = new Regex(pattern, RegexOptions.IgnoreCase).Matches(input);
+            foreach (Match match in matches)
+                Console.WriteLine(match.Value);
+
+            // This code prints the following output:
+            //
+            // The
+            // archive
+            // trimmed
+            // and
+            // tagged
+            #endregion
+
+            Assert.Equal(5, matches.Count);
+            Assert.Equal("The", matches[0].Value);
+            Assert.Equal("archive", matches[1].Value);
+            Assert.Equal("trimmed", matches[2].Value);
+            Assert.Equal("and", matches[3].Value);
+            Assert.Equal("tagged", matches[4].Value);
+        }
+
+        [Fact]
+        public static void ConstructorWithPatternOptionsAndMatchTimeout()
+        {
+            #region RegexCtorStringOptionsMatchTimeout
+            string pattern = @"(a+)+$";
+            string input = new string('a', 15) + "!";
+            TimeSpan timeout = TimeSpan.FromTicks(1);
+            bool isMatch;
+
+            try
+            {
+                isMatch = new Regex(pattern, RegexOptions.None, timeout).IsMatch(input);
+            }
+            catch (RegexMatchTimeoutException)
+            {
+                timeout = TimeSpan.FromSeconds(3);
+                isMatch = new Regex(pattern, RegexOptions.None, timeout).IsMatch(input);
+            }
+
+            Console.WriteLine($"Match found: {isMatch}");
+
+            // This code prints the following output:
+            //
+            // Match found: False
+            #endregion
+
+            Assert.False(isMatch);
+        }
+    }
 }