.NET 10.0 API Documentation Tracking Issue

[ericstj]

.NET 10.0 API Documentation Tracking Issue

This issue tracks the overall progress of documenting 1924 APIs added in .NET 10.0 across 29 namespaces.

Overview

This is a coordinated effort to ensure all .NET 10.0 APIs have proper documentation following the established patterns from previous .NET documentation.

Progress by Namespace

The following namespace-specific issues need to be completed:

Namespace	APIs	Issue
Microsoft.Extensions.*	89	#120513
System	29	#120512
System.IO.Compression	24	#120495
System.Linq	2	#120496
System.Net	4	#120499
System.Net.Security	3	#120497
System.Net.WebSockets	1	#120498
System.Numerics	187	#120500
System.Reflection	1	#120501
System.Runtime.CompilerServices	14	#120502
System.Runtime.ExceptionServices	2	#120503
System.Runtime.InteropServices	6	#120505
System.Runtime.InteropServices.Java	13	#120504
System.Runtime.Intrinsics	68	#120508
System.Runtime.Intrinsics.Arm	752	#120506
System.Runtime.Intrinsics.X86	719	#120507
System.Runtime.Serialization.DataContracts	7	#120509
System.Text	1	#120510
System.Xml	2	#120511

Instructions for Contributors

1. Choose a namespace issue from the list above
2. Determine if the the source assembly is documented in C# or directly in the dotnet-api-docs repo. The default in dotnet/runtime is to be documented in C#. If a project sets UseCompilerGeneratedDocXmlFile to false then it is documented in dotnet-api-docs.

Documenting in C#

1. Identify which APIs are missing documentation and what sort of documentation is missing. This can be done by examining the report, or clicking on the link to the missing docs.
2. Add the documentation directly in the C# source.
3. Use <inheritdoc/> if you don't need to change the documentation provided by an overidden member.
4. For .NET 10.0 we should backport these changes to release/10.0 branch. So long as your change only touches documentation it can be tell-mode but do minimize the number of PRs and be sure to have the change reviewed.

Documenting in dotnet-api-docs

1. Identify which APIs are missing documentation and what sort of documentation is missing. This can be done by examining the report, or clicking on the link to the missing docs.
2. Clone the https://github.com/dotnet/dotnet-api-docs to make your changes.
3. If you want to keep the C# docs up to date, you may start by modifying those as is described above in Documenting in C#. If you choose to do this, build your library then port over the changes manually using https://github.com/dotnet/api-docs-sync/blob/main/docs/PortToDocs.md. This will automate steps 4 and 5 below. Make sure to point the tool at the obj folder intermediates as this has your /// docs whereas bin has those that are generated from dotnet-api-docs.
4. Review the entries in the docs that say To Be Added and fill them in with appropriate detail.
5. Consider if this API can use <inheritdoc/> which may be the case for overrides or interface implementation. If so, leave the undocumented members alone and simply add <inheritdoc/>. This will document the API and avoid duplication.
6. Open a PR in dotnet-api-docs and tag @gewarren and other colleagues for review.
7. Once the PR is built you can examine the result of your docs changes by accessing the test instance of the docs:
   https://review.learn.microsoft.com/<pathToDocs>?branch=main&branchFallbackFrom=<nameOfPR>
   Similar links are available in the details link from the OpenPublishing.Build check.

Coordination

• Assign yourself to the specific namespace issue you're working on to avoid duplication
• Feel free to ask questions or request clarification in the individual namespace issues - tag @ericstj @jeffhandley @gewarren
• This tracking issue will be updated as namespace issues are completed

Total APIs to document: 1924
Total namespaces: 29

The full report of missing docs is here
UndocAPIReport_github.com_dotnet_dotnet-api-docs_main_dotnet-api-docs.xlsx