Move remarks back from conceptual docs repo

[gewarren]

Contributes to dotnet/dotnet-api-docs#12613.

We're moving supplemental API remarks out of the dotnet/docs repo and back into either:

• The /// (like this PR, for libraries that already have their source of truth here)
• The dotnet-api-docs repo, in preparation for backporting to ///

[gewarren]

Do I need to do something to get this compile-checked?

[gewarren]

Also, should this file be named System.Text.RegularExpressions/Regex.Examples.cs?

[jkotas]

Do I need to do something to get this compile-checked?

To validate whether the samples compile and run, I think we want to have them to be part of regular tests. In this case, it would mean to moving the file to src\libraries\System.Text.RegularExpressions\tests\FunctionalTests\ and annotating the Run method with the [Fact] attribute. Is the doc build system going to be able to strip the [Fact] attribute?

should this file be named Regex.Examples.cs?

Sounds reasonable to me. It assumes that all RegEx examples are going to be in a single file. If the assumption does not hold, we can always refactor it as needed.

[AaronRobinsonMSFT]

Another way to consider this would be to rename Run to Main and use the app project scenario. I do agree having it in the unit tests make sense, but then we need some "clean up for doc" step. It doesn't seem unreasonable to figure out some way to run them naturally with the local build. Perhaps a higher level "RunSnippets" project that run calls them?

[gewarren]

Back in February in the "/// FTW" chat (Aaron - should I add you to that discussion about backporting docs?), Jan and Eric agreed that these examples shouldn't go in the 'tests' directory. Eric also said this:

We can have a samples folder for these and minimize the additional projects - one for all lib samples, and one for each "program" sample. They can build at the same time as the tests, and the tests can even target them if they need to run them to validate their behavior.

So can you clarify what I should do here?

[jkotas]

Is the file with sample API usage going to be referenced directly from compiled docs that you see on https://learn.microsoft.com/, or is it going to be sliced and reformatted before it gets included in the compiled docs?

I think we have two options:

• Add a boilerplate around the API usage samples that turn it into regular test. Use regular test infrastructure to validate the samples. This assume that the process that produces compiled docs is strips the boilerplate, like the [Fact] attribute.
• Keep the files with API usage samples free of any boilerplate, and create a dedicated infra to build and run the API usage samples. This is more expensive to maintain and run over time.

For the sample location, my requirement is that it is immediately clear when looking at a piece of code that it is an API usage example. It can be a subdirectory name, it can be a file name pattern, it can be a type or method name pattern. Any one of these options works for me.

Once we agree on the details, we should add a new section with the guideline for samples under https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/adding-api-guidelines.md#documentation .

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

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

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.