System.Buffers: Backport MS Docs documentation to triple slash

[carlossanlop]

We are working on a new documentation process plan, in which the main objective is to make triple slash comments the source of truth for documentation, instead of MS Docs: We want developers/maintainers to have an easier time maintaining the documentation for their APIs.

You can use the DocsPortingTool to automate the backport process: Run the tool targeting the assembly, then submit a PR with the changes.

You can find detailed instructions for the backporting process here.

Area owners are free to decide if they want to address this in 6.0 or in Future.

[ghost]

Tagging subscribers to this area: @tannergooding, @pgovind, @GrabYourPitchforks
See info in area-owners.md if you want to be subscribed.

Issue Details

---

We are working on a new documentation process plan, in which the main objective is to make triple slash comments the source of truth for documentation, instead of MS Docs: We want developers/maintainers to have an easier time maintaining the documentation for their APIs.

You can use the DocsPortingTool to automate the backport process: Run the tool targeting the assembly, then submit a PR with the changes.

You can find detailed instructions for the backporting process here.

Area owners are free to decide if they want to address this in 6.0 or in Future.

Author:	carlossanlop
Assignees:	-
Labels:	area-System.Buffers, documentation
Milestone:	-

[jeffhandley]

I tried to port these docs but I ran into some issues with the DocsPortingTool. I'm still investigating, but it seems to be related to many of the source files for System.Buffers being pulled in through the System.Private.CoreLib.Shared.shproj project. Even though files like ArrayPool.cs are included in the shproj, they never show up as included in either the System.Buffers project or the System.Private.CoreLib project, which seems to be preventing the DocsPortingTool from finding them.

[jeffhandley]

This is blocked by:

• Use the correct type name for generic and nested types api-docs-sync#63
• Pragmas before types and members get dropped when porting docs into triple slash comments api-docs-sync#65
• Some xrefs for generics produce invalid triple slash comments api-docs-sync#66

[jeffhandley]

We are closing all of the issues for backporting api docs to triple-slash comments for now. We concluded early in the .NET 7.0 release cycle that we need to invest more into the DocsPortingTool to set this effort up for success. When we're able to revisit this, we will open new issues per area again.