Documenting .NET 8.0 APIs

[carlossanlop]

The table below shows the namespaces that added APIs in 8.0 and need their documentation to be ported to dotnet-api-docs.

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

• We ensure the docs go through language review there via a PR.
• We use that language-reviewed content to generate the official intellisense xmls that we then ship to customers.

In the table below, each namespace is assigned an issue containing a detailed list of the APIs that show up as undocumented in dotnet-api-docs, as well as 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 before the RC2 snap (September 17th).

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 sets the <UseCompilerGeneratedDocXmlFile> property to true (example). For such assemblies, you only need to add the missing documentation in 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 <UseIntellisensePackageDocXmlFile> property is unset or is set to true, then it means dotnet-api-docs is its source of truth. If that's your case, 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.

Namespace	2023/07/09	Issue
System.Runtime.Intrinsics.X86	905	#88574
System.Runtime.Intrinsics.Wasm	396	#88574
System.Runtime.Intrinsics	320	#88574
System	131	#88563
System.Reflection.Emit	115	#88571
System.Runtime.InteropServices.Marshalling	97	#88573
System.Collections.Frozen	94	#88565
System.Text	49	#88576
System.Numerics	47	#88570
System.Buffers.Binary	46	#88564
System.Diagnostics.Metrics	34	#88567
System.Net	33	#88569
System.Security.Cryptography	33	#88575
System.IO.Hashing	32	#88568
System.Text.Json	30	#88577
System.Runtime.Intrinsics.Arm	24	#88574
System.ComponentModel.DataAnnotations	19	#88566
System.Text.Unicode	17	#88576
System.Text.Json.Serialization	16	#88577
System.Threading.Tasks	15	#88578
Microsoft.Extensions.Http.Resilience	14	dotnet/extensions#4164
Microsoft.Extensions.Resilience.Options	11	dotnet/extensions#4164
System.Reflection	9	#88571
Microsoft.Extensions.Options	8	dotnet/extensions#4164
Microsoft.Extensions.Resilience.FaultInjection	8	dotnet/extensions#4164
System.Collections.Generic	8	#88565
System.Runtime.InteropServices	8	#88573
System.Cloud.DocumentDb	7	dotnet/extensions#4163
System.Runtime.CompilerServices	7	dotnet/dotnet-api-docs#9131
Microsoft.Extensions.Compliance.Redaction	6	#88562
System.Threading	6	#88578
Microsoft.Extensions.Telemetry.Enrichment	5	dotnet/extensions#4164
Microsoft.Extensions.Time.Testing	5	dotnet/extensions#4164
System.Buffers	5	#88564
System.Diagnostics	5	#88567
Microsoft.Extensions.Diagnostics.HealthChecks	4	dotnet/extensions#4164
Microsoft.Extensions.Diagnostics.ResourceMonitoring	4	dotnet/extensions#4164
Microsoft.Extensions.Hosting	4	dotnet/extensions#4164
Microsoft.Extensions.Hosting.Testing	4	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Logging	4	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Tracing	4	dotnet/extensions#4164
System.Buffers.Text	4	#88564
System.Collections.ObjectModel	4	#88565
System.Linq	4	#88589
System.Net.Security	4	#88569
System.Reflection.Metadata.Ecma335	4	#88571
System.Text.Json.Serialization.Metadata	4	#88577
Microsoft.Extensions.Compliance.Testing	3	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Console	3	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Latency	3	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Metering	3	dotnet/extensions#4164
System.Net.Quic	3	#88569
Microsoft.Extensions.AmbientMetadata	2	dotnet/extensions#4164
Microsoft.Extensions.DependencyInjection	2	#88562
Microsoft.Extensions.Http.AutoClient	2	dotnet/extensions#4164
Microsoft.Extensions.Http.Logging	2	#88562
Microsoft.Extensions.Http.Telemetry.Latency	2	dotnet/extensions#4164
Microsoft.Extensions.Http.Telemetry.Logging	2	dotnet/extensions#4164
Microsoft.Extensions.Http.Telemetry.Tracing	2	dotnet/extensions#4164
Microsoft.Extensions.ObjectPool	2	dotnet/extensions#4164
Microsoft.Extensions.Options.Contextual	2	dotnet/extensions#4164
Microsoft.Extensions.Options.Validation	2	#88562
Microsoft.Extensions.Resilience	2	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Testing.Logging	2	dotnet/extensions#4164
System.Collections	2	#88565
System.Collections.Immutable	2	#88565
System.Globalization	2	dotnet/dotnet-api-docs#9131
System.IO	2	#88568
System.Net.Http.Json	2	#88569
System.Net.NetworkInformation	2	#88569
System.Reflection.PortableExecutable	2	#88571
Microsoft.Extensions.AsyncState	1	dotnet/extensions#4164
Microsoft.Extensions.Compliance.Classification	1	dotnet/extensions#4164
Microsoft.Extensions.Diagnostics.ExceptionSummarization	1	dotnet/extensions#4164
Microsoft.Extensions.Diagnostics.Metrics	1	#88562
Microsoft.Extensions.EnumStrings	1	dotnet/extensions#4164
Microsoft.Extensions.Http.Resilience.FaultInjection	1	dotnet/extensions#4164
Microsoft.Extensions.Http.Telemetry	1	dotnet/extensions#4164
Microsoft.Extensions.Http.Telemetry.Metering	1	dotnet/extensions#4164
Microsoft.Extensions.Telemetry	1	dotnet/extensions#4164
Microsoft.Extensions.Telemetry.Testing.Metering	1	dotnet/extensions#4164
System.Cloud.Messaging	1	dotnet/extensions#4163
System.CodeDom.Compiler	1	dotnet/dotnet-api-docs#9131
System.Data.SqlTypes	1	dotnet/dotnet-api-docs#9131
System.IO.MemoryMappedFiles	1	#88568
System.Net.Sockets	1	#88569
System.Net.WebSockets	1	#88569
Total	2682

cc @jeffhandley @ericstj @karelz

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

Issue Details

---

The table below shows the namespaces that added APIs in 8.0 and need their documentation to be ported to dotnet-api-docs.

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

• We ensure the docs go through language review there via a PR.
• We use that language-reviewed content to generate the official intellisense xmls that we ship to customers.

In the table, each namespace is assigned an issue containing a detailed list of the APIs that show up as undocumented in dotnet-api-docs, as well as the exact xml element that needs to be documented. Please look at that table, confirm each one of those APIs is properly documented in triple slash comments in runtime, and then follow the porting instructions below.

Important: These issues are marked as blocking-release. The task needs to be completed before the RC2 snap (September 18th).

Porting instructions

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, build the assembly that you desire to port.

   1. If it's a regular assembly, build the src csproj:

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

   2. If the APIs are defined inside System.Private.Corelib:

       cd runtime
       build.cmd clr.corelib -rc release
      

      Your resulting xml file will be located under artifacts/bin/coreclr/<OS>.<ARCH>.<CONFIG>/IL/, for example: artifacts/bin/coreclr/windows.arm64.Release/IL/. Make note of this folder for later.

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\bin"\
            -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" \
            -IncludedAssemblies "System.Runtime" \
            -IncludedNamespaces "System.IO" \
            -SkipInterfaceImplementations true \
            -Save true
      

   Note: 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.

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

Namespace	2023/07/09	Issue
System.Runtime.Intrinsics.X86	905
System.Runtime.Intrinsics.Wasm	396
System.Runtime.Intrinsics	320
System	131
System.Reflection.Emit	115
System.Runtime.InteropServices.Marshalling	97
System.Collections.Frozen	94
System.Text	49
System.Numerics	47
System.Buffers.Binary	46
System.Diagnostics.Metrics	34
System.Net	33
System.Security.Cryptography	33
System.IO.Hashing	32
System.Text.Json	30
System.Runtime.Intrinsics.Arm	24
System.ComponentModel.DataAnnotations	19
System.Text.Unicode	17
System.Text.Json.Serialization	16
System.Threading.Tasks	15
Microsoft.Extensions.Http.Resilience	14
Microsoft.Extensions.Resilience.Options	11
System.Reflection	9
Microsoft.Extensions.Options	8
Microsoft.Extensions.Resilience.FaultInjection	8
System.Collections.Generic	8
System.Runtime.InteropServices	8
System.Cloud.DocumentDb	7
System.Runtime.CompilerServices	7
Microsoft.Extensions.Compliance.Redaction	6
System.Threading	6
Microsoft.Extensions.Telemetry.Enrichment	5
Microsoft.Extensions.Time.Testing	5
System.Buffers	5
System.Diagnostics	5
Microsoft.Extensions.Diagnostics.HealthChecks	4
Microsoft.Extensions.Diagnostics.ResourceMonitoring	4
Microsoft.Extensions.Hosting	4
Microsoft.Extensions.Hosting.Testing	4
Microsoft.Extensions.Telemetry.Logging	4
Microsoft.Extensions.Telemetry.Tracing	4
System.Buffers.Text	4
System.Collections.ObjectModel	4
System.Linq	4
System.Net.Security	4
System.Reflection.Metadata.Ecma335	4
System.Text.Json.Serialization.Metadata	4
Microsoft.Extensions.Compliance.Testing	3
Microsoft.Extensions.Telemetry.Console	3
Microsoft.Extensions.Telemetry.Latency	3
Microsoft.Extensions.Telemetry.Metering	3
System.Net.Quic	3
Microsoft.Extensions.AmbientMetadata	2
Microsoft.Extensions.DependencyInjection	2
Microsoft.Extensions.Http.AutoClient	2
Microsoft.Extensions.Http.Logging	2
Microsoft.Extensions.Http.Telemetry.Latency	2
Microsoft.Extensions.Http.Telemetry.Logging	2
Microsoft.Extensions.Http.Telemetry.Tracing	2
Microsoft.Extensions.ObjectPool	2
Microsoft.Extensions.Options.Contextual	2
Microsoft.Extensions.Options.Validation	2
Microsoft.Extensions.Resilience	2
Microsoft.Extensions.Telemetry.Testing.Logging	2
System.Collections	2
System.Collections.Immutable	2
System.Globalization	2
System.IO	2
System.Net.Http.Json	2
System.Net.NetworkInformation	2
System.Reflection.PortableExecutable	2
Microsoft.Extensions.AsyncState	1
Microsoft.Extensions.Compliance.Classification	1
Microsoft.Extensions.Diagnostics.ExceptionSummarization	1
Microsoft.Extensions.Diagnostics.Metrics	1
Microsoft.Extensions.EnumStrings	1
Microsoft.Extensions.Http.Resilience.FaultInjection	1
Microsoft.Extensions.Http.Telemetry	1
Microsoft.Extensions.Http.Telemetry.Metering	1
Microsoft.Extensions.Telemetry	1
Microsoft.Extensions.Telemetry.Testing.Metering	1
System.Cloud.Messaging	1
System.CodeDom.Compiler	1
System.Data.SqlTypes	1
System.IO.MemoryMappedFiles	1
System.Net.Sockets	1
System.Net.WebSockets	1
Total	2682

cc @jeffhandley @ericstj @karelz

Author:	carlossanlop
Assignees:	carlossanlop
Labels:	documentation, area-Infrastructure-libraries, blocking-release
Milestone:	8.0.0