dotnet / dotnet/runtime

.NET 10.0 API Documentation Tracking Issue

Open
#120,483 2 comments 0 reactions 0 assignees View on GitHub
area-Meta documentation
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

# .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 `` 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 http://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#](#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 `` which may be the case for overrides or interface implementation. If so, leave the undocumented members alone and simply add ``. 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/?branch=main&branchFallbackFrom=`
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](https://github.com/user-attachments/files/22754796/UndocAPIReport_github.com_dotnet_dotnet-api-docs_main_dotnet-api-docs.xlsx)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.