Documenting .NET 9 APIs

[carlossanlop]

The table below shows the namespaces that added APIs in .NET 9 and do not yet have any documentation in dotnet-api-docs.

The dotnet-api-docs repo is currently our source of truth for documentation for two reasons:

• We ensure the docs go through language review there via a PR (it happens in dotnet-api-docs)
• We use that language-reviewed content to generate the official intellisense xmls that we then ship to customers (this is fed back to dotnet/runtime via an internal package)

The documentation in triple slash comments in source code needs to be manually ported to dotnet-api-docs to ensure the above process is done. We already ported all existing docs for .NET 9 APIs (here and here), but there are still some that show up as undocumented.

In the table below, each namespace is assigned an issue that contains a detailed list of the APIs that show up as undocumented in dotnet-api-docs, and the exact xml element that needs to be documented. Please look at your undoc APIs and follow the instructions below for documenting them.

Important: These issues are marked as blocking-release. All new APIs need to documented the day before the RC2 snap (September 15th).

Namespace	08-20 (P7)	Issue
System.Numerics	146	#105981
System	41	#105987
System.ComponentModel	17	#105983
System.Linq	7	#105984
System.Collections.Generic	5	#105974
System.Collections.Frozen	5	#105974
System.Threading.Tasks	5	#105985
System.Diagnostics	5	#105980
System.Collections.Concurrent	4	#105974
System.Net.Quic	4	#106789
System.Security.Cryptography	4	#106790
System.IO	3	#105979
System.Net.Http	3	#106789
System.Data	1	dotnet/dotnet-api-docs#10294
System.Formats.Tar	1	dotnet/dotnet-api-docs#10294
Total	251

Namespace	08-20 (P7)	08-15 (P6)
System.Runtime.Intrinsics.Arm	1680	1247
System.Runtime.Intrinsics.X86	597	609
System.Runtime.Intrinsics	80	72
Total	2357	1928

Intrinsics issue: #105989

Namespace	08-20 (P7)	08-15 (P6)
System.Drawing.Imaging.Effects	80	80
System.Drawing	42	42
System.Drawing.Drawing2D	34	32
System.Drawing.Imaging	31	31
Total	187	185

Drawing issue: dotnet/winforms#11858

Instructions

First, determine what's the documentation source of truth for your assembly:

A) Your assembly uses triple slash comments as the source of truth - You'll know this if your assembly's src csproj does not set the <UseCompilerGeneratedDocXmlFile> property, or it explicilty sets it to true (example). Note that the default value for that property is true so usually it will just be absent. For such assemblies, you only need to add the missing documentation in the source code triple slash comments directly and send a PR in runtime. After merged, your documentation should show up in MS Docs in the next preview release automatically.
Note: After the RC1 snap (August 14th), you'll also have to backport your PR to the RC1 branch.

B) If the <UseCompilerGeneratedDocXmlFile> property is set to false, then it means it is still using dotnet-api-docs as its source of truth. If your assembly uses false, then follow the "porting to dotnet-api-docs" instructions below.

Porting to dotnet-api-docs

1. Clone the three involved repos locally if you haven't yet done so:

    git clone https://github.com/dotnet/runtime
    git clone https://github.com/dotnet/dotnet-api-docs
    git clone https://github.com/dotnet/api-docs-sync
   

2. Run the api-docs-sync install-as-tool.ps1 script to get the docs porting tool installled as a global dotnet tool.

3. In the runtime clone, document the APIs, then build their assembly:

   a) If it's a regular libraries assembly, build the src csproj:

     cd runtime/src/libraries/System.Formats.Tar
     dotnet build src/System.Formats.Tar.csproj
   

   b) If the APIs are defined inside System.Private.CoreLib:

      cd runtime
      build.cmd clr.corelib -rc release
   

4. Port the xml docs from runtime into dotnet-api-docs running this command:

    PortToDocs \
        -Docs <pathToDocsXmlFolder> \
        -IntelliSense <pathToArtifactsFolder1>[,<pathToArtifactsFolder2>,...,<pathToArtifactsFolderN>] \
        -IncludedAssemblies <assembly1>[,<assembly2>,...<assemblyN>] \
        -IncludedNamespaces <namespace1>[,<namespace2>,...,<namespaceN>] \
        -SkipInterfaceImplementations [true|false] \
        -Save true
   

   1. Example if it's a regular assembly:

       PortToDocs \
            -Docs "C:\path\to\dotnet-api-docs\xml" \
            -IntelliSense "C:\path\to\runtime\artifacts\obj" \
            -IncludedAssemblies "System.Formats.Tar" \
            -SkipInterfaceImplementations true \
            -Save true
      

   2. If the APIs are defined under System.Private.CoreLib (for example, APIs from System.IO, System.Text, System.Globalization or System.Numerics):

       PortToDocs \
            -Docs "C:\path\to\dotnet-api-docs\xml" \
            -IntelliSense "C:\path\to\runtime\artifacts\bin\coreclr" \
            -IncludedAssemblies "System.Runtime,System.Private.CoreLib" \
            -IncludedNamespaces "System.IO" \
            -SkipInterfaceImplementations true \
            -Save true
      

Notes

• If your undocumented list contains APIs that are explicit interface implementations and use <inheritdoc/>, set the SkipInterfaceImplementations argument to false or remove it altogether. The tool will import all interfaces and will try to find and copy the parent interface's documentation for you.

• Also notice that coreclr uses bin, while libraries uses obj.

5. Submit a dotnet-api-docs PR and tag @gewarren and @carlossanlop for language review.

cc
Libraries APIs: @jeffhandley @ericstj @SamMonoRT @artl93 @stephentoub
coreclr APIs: @jeffschwMSFT @agocke @tommcdon @JulieLeeMSFT
Drawing APIs: @JeremyKuhne @merriemcgaw

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-meta
See info in area-owners.md if you want to be subscribed.