Backport System.Text.RegularExpressions XML docs from dotnet-api-docs to source

[danmoseley]

Note

This PR description was AI/Copilot-generated.

Motivation

New APIs like RegexOptions.AnyNewLine and RegexOptions.NonBacktracking have documentation in source code but only "To be added." stubs in the dotnet-api-docs repo, so they show up undocumented on learn.microsoft.com. Similarly, GeneratedRegexAttribute members were documented in source but stubbed in the docs repo.

Rather than patch these individually in the docs repo, this PR makes the source code the single source of truth by backporting the richer dotnet-api-docs content into /// comments and flipping the UseCompilerGeneratedDocXmlFile switch. This is part of the broader initiative tracked in dotnet/dotnet-api-docs#10722.

What changed

• 24 files in src/libraries/System.Text.RegularExpressions/src/ — all changes are XML doc comments (///), with these exceptions:
  • Removed <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile> from the csproj (flips the switch so compiler-generated XML becomes authoritative)
  • Converted inline // comments on protected fields in Regex.cs to /// XML doc comments (required to avoid CS1591 errors)
  • Removed a // Callback class comment in RegexRunnerFactory.cs (replaced by /// <summary>)
• No behavioral code changes.

Merge strategy

• Default: dotnet-api-docs text wins — richer, editor-reviewed content preferred over minimal source stubs
• Source text kept where docs-repo was missing — AnyNewLine, NonBacktracking, GeneratedRegexAttribute members had docs in source but only "To be added." in the docs repo
• .NET Framework-specific content stripped — CompileToAssembly remarks, Framework version notes, etc.

Format conversion

Docs-repo uses a custom XML/Markdown hybrid format. This was converted to standard /// XML:

docs-repo	source ///
<format type="text/markdown">	<remarks>, <para>, <list>
Backtick code	<c>...</c>
[text](url)	<see href="url">text</see>
Markdown tables	<list type="table">

Follow-up needed (by docs team)

Per the process in dotnet/dotnet-api-docs#10722:

• Add System.Text.RegularExpressions namespace to disallow-edits.yml
• Set open_to_public_contributors to false in the API docs repo
• Add to the docs CI pipeline for ongoing validation

Testing

• Build: 0 errors, 0 warnings (Release)
• Tests: net481 (15,932 passed), net11.0 (32,068 passed)

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-text-regularexpressions
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

Backports richer XML documentation for System.Text.RegularExpressions APIs into source /// comments so IntelliSense and generated docs can be sourced from the runtime repo.

Changes:

• Expanded/standardized XML doc comments across System.Text.RegularExpressions public surface area (types, members, exceptions, remarks).
• Added XML docs for previously undocumented/protected members to avoid doc warnings (e.g., protected fields / constructors).
• Updated project configuration by removing <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile> so compiler-generated XML becomes authoritative.

Show a summary per file

File	Description
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/ValueMatch.cs	Refined XML docs for ValueMatch and its members.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexRunnerFactory.cs	Added XML docs for extensibility factory type/members.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexRunner.cs	Added/converted XML docs for runner APIs and helpers.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexParseException.cs	Improved exception XML docs for parsing failures.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexParseError.cs	Fixed/standardized enum value docs formatting.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexOptions.cs	Added comprehensive option/member docs with links/remarks.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexMatchTimeoutException.cs	Expanded exception docs incl. constructors/serialization/properties.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/RegexCompilationInfo.cs	Added docs clarifying obsolescence / source generator guidance.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.cs	Added class/field/ctor/member docs and richer remarks.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Timeout.cs	Expanded time-out related docs and remarks.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Split.cs	Expanded XML docs for Split overloads.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Replace.cs	Expanded XML docs for Replace overloads and MatchEvaluator.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Match.cs	Expanded XML docs for IsMatch/Match/Matches overloads.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.EnumerateSplits.cs	Adjusted XML docs for split enumerator APIs.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.EnumerateMatches.cs	Expanded XML docs for match enumerator APIs.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Cache.cs	Added docs for Regex.CacheSize and cache behavior.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/MatchCollection.cs	Expanded collection docs (lazy vs direct eval, members, exceptions).
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Match.cs	Replaced internal block comments with public-facing XML docs.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/GroupCollection.cs	Expanded group collection docs and member documentation.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Group.cs	Added richer docs for group semantics and captures.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/GeneratedRegexAttribute.cs	Reflowed/standardized attribute docs and remarks.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/CaptureCollection.cs	Expanded capture collection docs and member documentation.
src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Capture.cs	Expanded capture docs (properties/remarks/ToString).
src/libraries/System.Text.RegularExpressions/src/System.Text.RegularExpressions.csproj	Removed explicit opt-out of compiler-generated XML doc output.

Copilot's findings

Comments suppressed due to low confidence (4)

src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Split.cs:72

• In XML docs, <see cref="Regex"/>.Split won’t link to the Split methods. Consider using <see cref="Regex.Split(string)"/> (or an appropriate overload) instead of linking only to the type.

        /// The <see cref="Regex"/>.Split methods are similar to the
        /// <see cref="string.Split(char[])"/> method, except that <see cref="Regex"/>.Split splits

src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Split.cs:125

• In XML docs, <see cref="Regex"/>.Split doesn’t produce a method link. Prefer a <see cref="..."/> that targets the relevant Split overload (e.g. <see cref="Regex.Split(string)"/>) so IntelliSense links correctly.

        /// The <see cref="Regex"/>.Split methods are similar to the
        /// <see cref="string.Split(char[])"/> method, except that <see cref="Regex"/>.Split splits

src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Split.cs:163

• These remarks use <see cref="Regex"/>.Split, which links only to the Regex type, not the Split methods. Consider switching to a specific overload like <see cref="Regex.Split(string)"/> and then referring to “this method” in text.

        /// The <see cref="Regex"/>.Split methods are similar to the
        /// <see cref="string.Split(char[])"/> method, except that <see cref="Regex"/>.Split splits

src/libraries/System.Text.RegularExpressions/src/System/Text/RegularExpressions/Regex.Split.cs:206

• <see cref="Regex"/>.Split won’t resolve as a method link in generated docs/IntelliSense. Prefer <see cref="Regex.Split(string, int)"/> (or whatever overload is being discussed) and tweak the prose to match.

        /// The <see cref="Regex"/>.Split methods are similar to
        /// <see cref="string.Split(char[])"/>. The <paramref name="count"/> parameter specifies

• Files reviewed: 24/24 changed files
• Comments generated: 4

[Copilot]

Copilot's findings

• Files reviewed: 24/24 changed files
• Comments generated: 2