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

[gewarren]

We can reference a region of a file, so in that way it can be sliced and diced. But otherwise it's WYSIWYG.

For Newtonsoft, it looks like their examples are coming from their test code:

https://github.com/JamesNK/Newtonsoft.Json/blob/master/Src/Newtonsoft.Json/Linq/JObject.cs#L54

[jkotas]

For Newtonsoft, it looks like their examples are coming from their test code:

They have regular tests and examples split. Regular tests are in directories like Src/Newtonsoft.Json.Tests/Schema, examples are under Documentation directory like Src/Newtonsoft.Json.Tests/Documentation/JsonSchemaTests.cs . "Documentation" is not a very self-describing name for a directory with API examples. Otherwise, it looks reasonable to me.

This is my proposal for the guideline to be added to https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/adding-api-guidelines.md#documentation

---

API Usage Examples

API usage examples are included in the test sources so they can be validated during regular test runs. These examples should either be placed in the examples subdirectory or use a filename with the Examples suffix. depending on what's the best fit for the test project structure. The specific code intended for the published documentation is marked with a #region directive, which allows test-related boilerplate (such as the [Fact] attribute) to be excluded from the final documentation.

The API usage examples are referenced from the documentation using the code-csharp directive. For example:

[!code-csharp[](../../../../tests/System.Text.RegularExpressions/FunctionalTests/Regex.Examples.cs#Match)]

This directive pulls the code snippet identified by the specified #region from the source file and embeds it directly into the documentation.

[jkotas]

Could you please add this to 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.

[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 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[gewarren]

@jkotas I think I did everything as requested. Are the build failures related to my changes?

[jkotas]

Are the build failures related to my changes?

The build failures are unrelated.

Left a few comments. LGTM otherwise.

[jkotas]

Thank you!