Allow adding custom XML documentation to GeneratedRegex implementations

[waiwaing]

If you use a source-generated Regex, e.g.

[GeneratedRegex(@"^\d{3}$")]
public static partial Regex MyRegex();

a <remarks> section is automatically emitted by the RegexGenerator, e.g.

/// <remarks>
/// Pattern:<br/>
/// (elided as details are not relevant)
/// </remarks>
[global::System.CodeDom.Compiler.GeneratedCodeAttribute("System.Text.RegularExpressions.Generator", "8.0.11.1707")]
public static partial global::System.Text.RegularExpressions.Regex MyRegex() => global::System.Text.RegularExpressions.Generated.MyRegex_14.Instance;

As a result, it is in practice not possible to add custom XML documentation to the original partial method declaration, as Visual Studio will only use one set of XML documentation (and it appears that it seems to reliably prefer the generated docs).

I think there are two options to allow custom XML documentation to be added:

1. When processing the GeneratedRegexAttribute, pick up any XML documentation declared and merge it with the auto-generated documentation when emitting the generated code. If the user does not declare a <remarks> or <inheritdoc> section, then merging should be straightforward; however, some thought as to best behaviour if either section is declared is probably needed.

   1. As an alternative, if the user does have XML documentation, do not emit any auto-generated documentation to ensure Visual Studio picks up the user's version.

2. Allow a new boolean argument on GeneratedRegexAttribute to disable the auto-generated documentation. I think this is strictly worse than the first option, so would only suggest it if it is not possible for whatever reason to detect if the user has added any XML documentation.

[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.

[stephentoub]

Thanks, your suggestions are reasonable. My hope, though, was that the scenario would instead be addressed by dotnet/roslyn#60730.
cc: @RikkiGibson