Documenting .NET 9 APIs

@gewarren

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

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

Run the api-docs-sync install-as-tool.ps1 script to get the docs porting tool installled as a global dotnet tool.
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
```

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

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

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.

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

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

A) Your assembly uses triple slash comments as the source of truth - You'll know this if your assembly's src csproj sets the property to true

Please update this paragraph as it isn't true anymore. That property defaults to true in main. Unless a project sets it to false, the project uses triple slash comments as the source of truth.

B) If the property is unset or is set to false,

Similarly, here it should say "if the property is set to false". Unset now means A and not B.

@ViktorHofer

Thanks, fixed, @ViktorHofer .

@ViktorHofer

@ViktorHofer when did that change go in? That property was unset in System.Numerics until yesterday, and enabling it immediately had a bunch of build failures. If that property was enabled by default I wouldn't have expected that behavior.

There might be a bug in the logic. If the property is unset, it should be treated as true, but maybe we're not doing that, hence why you started seeing the failures when you set it to true explicitly. But this is a hypothesis, I'll have to dig in to confirm.

@michaelgsharp

@michaelgsharp Just to double check that we are talking about the same thing please elaborate on:

which project
which property
and what are the exact build failures

For System.Numerics.Vectors the UseCompilerGeneratedDocXmlFile property is explicitly set to false which silences the CS1591 errors:

runtime/src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj

Line 6 in 019d758

<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>

That's the expected behavior. FWIW if I remove that property (or set it to true), I don't get any build errors.

We inspected the package in the transport feed. No xmls are getting included anymore. And this regression was introduced in the same PR that inverted the value of UseCompilerGeneratedDocXmlFile. The problem is that if the property is absent, it is not being treated as true, as we expected.

@carlossanlop

@carlossanlop do we also need an issue for Microsoft.Extensions.Http? Fixing the switch causes these two undocumented public APIs to error:

runtime/src/libraries/Microsoft.Extensions.Http/src/DependencyInjection/HttpClientBuilderExtensions.cs

Lines 648 to 705 in 99f7f93

    
           public static IHttpClientBuilder AddAsKeyed(this IHttpClientBuilder builder, ServiceLifetime lifetime = ServiceLifetime.Scoped) 
        
           { 
        
               ThrowHelper.ThrowIfNull(builder); 
        
               string? name = builder.Name; 
        
               IServiceCollection services = builder.Services; 
        
               HttpClientMappingRegistry registry = GetMappingRegistry(services); 
        
               UpdateEmptyNameHttpClient(services, registry); 
        
               if (name == null) 
        
               { 
        
                   registry.DefaultKeyedLifetime?.RemoveRegistration(services); 
        
                   registry.DefaultKeyedLifetime = new HttpClientKeyedLifetime(lifetime); 
        
                   registry.DefaultKeyedLifetime.AddRegistration(services); 
        
               } 
        
               else 
        
               { 
        
                   if (registry.KeyedLifetimeMap.TryGetValue(name, out HttpClientKeyedLifetime? clientLifetime)) 
        
                   { 
        
                       clientLifetime.RemoveRegistration(services); 
        
                   } 
        
                   clientLifetime = new HttpClientKeyedLifetime(name, lifetime); 
        
                   registry.KeyedLifetimeMap[name] = clientLifetime; 
        
                   clientLifetime.AddRegistration(services); 
        
               } 
        
               return builder; 
        
           } 
        
           public static IHttpClientBuilder RemoveAsKeyed(this IHttpClientBuilder builder) 
        
           { 
        
               ThrowHelper.ThrowIfNull(builder); 
        
               string? name = builder.Name; 
        
               IServiceCollection services = builder.Services; 
        
               HttpClientMappingRegistry registry = GetMappingRegistry(services); 
        
               UpdateEmptyNameHttpClient(services, registry); 
        
               if (name == null) 
        
               { 
        
                   registry.DefaultKeyedLifetime?.RemoveRegistration(services); 
        
                   registry.DefaultKeyedLifetime = HttpClientKeyedLifetime.Disabled; 
        
               } 
        
               else 
        
               { 
        
                   if (registry.KeyedLifetimeMap.TryGetValue(name, out HttpClientKeyedLifetime? clientLifetime)) 
        
                   { 
        
                       clientLifetime.RemoveRegistration(services); 
        
                   } 
        
                   registry.KeyedLifetimeMap[name] = HttpClientKeyedLifetime.Disabled; 
        
               } 
        
               return builder; 
        
           }

Submitted #106179 to fix the wrong default

@ViktorHofer

@ViktorHofer not sure when those APIs were introduced to runtime in main. There's a chance they were introduced in Preview7. Remember that the dotnet-api-docs APIs are always one preview behind (currently pointing at Preview6). So what you see as undocumented in runtime but not showing up in my tables might be because the API doesn't yet exist in dotnet-api-docs.

Navigation Menu

Repository navigation

Documenting .NET 9 APIs #105974

Instructions

Porting to dotnet-api-docs

Notes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	public static IHttpClientBuilder AddAsKeyed(this IHttpClientBuilder builder, ServiceLifetime lifetime = ServiceLifetime.Scoped)
	{
	ThrowHelper.ThrowIfNull(builder);

	string? name = builder.Name;
	IServiceCollection services = builder.Services;
	HttpClientMappingRegistry registry = GetMappingRegistry(services);

	UpdateEmptyNameHttpClient(services, registry);

	if (name == null)
	{
	registry.DefaultKeyedLifetime?.RemoveRegistration(services);

	registry.DefaultKeyedLifetime = new HttpClientKeyedLifetime(lifetime);
	registry.DefaultKeyedLifetime.AddRegistration(services);
	}
	else
	{
	if (registry.KeyedLifetimeMap.TryGetValue(name, out HttpClientKeyedLifetime? clientLifetime))
	{
	clientLifetime.RemoveRegistration(services);
	}

	clientLifetime = new HttpClientKeyedLifetime(name, lifetime);
	registry.KeyedLifetimeMap[name] = clientLifetime;
	clientLifetime.AddRegistration(services);
	}

	return builder;
	}

	public static IHttpClientBuilder RemoveAsKeyed(this IHttpClientBuilder builder)
	{
	ThrowHelper.ThrowIfNull(builder);

	string? name = builder.Name;
	IServiceCollection services = builder.Services;
	HttpClientMappingRegistry registry = GetMappingRegistry(services);

	UpdateEmptyNameHttpClient(services, registry);

	if (name == null)
	{
	registry.DefaultKeyedLifetime?.RemoveRegistration(services);
	registry.DefaultKeyedLifetime = HttpClientKeyedLifetime.Disabled;
	}
	else
	{
	if (registry.KeyedLifetimeMap.TryGetValue(name, out HttpClientKeyedLifetime? clientLifetime))
	{
	clientLifetime.RemoveRegistration(services);
	}
	registry.KeyedLifetimeMap[name] = HttpClientKeyedLifetime.Disabled;
	}

	return builder;
	}

Documenting .NET 9 APIs #105974

Description

Instructions

Porting to dotnet-api-docs

Notes

Activity

dotnet-policy-service commented on Aug 5, 2024

ViktorHofer commented on Aug 7, 2024

carlossanlop commented on Aug 7, 2024

michaelgsharp commented on Aug 7, 2024

carlossanlop commented on Aug 7, 2024

ViktorHofer commented on Aug 8, 2024

carlossanlop commented on Aug 8, 2024

ViktorHofer commented on Aug 9, 2024

ViktorHofer commented on Aug 9, 2024

carlossanlop commented on Aug 9, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions