Developers can access documentation for all .NET Core/.NET 5 APIs

[carlossanlop]

As part of the 7.0 goals, we want to finish documenting APIs that were shipped without triple slash documentation in previous .NET Core versions.

We expect developers to add documentation directly in triple slash comments in source, since it's new documentation. Triple slash are still going to be used for seeding dotnet-api-docs, which is considered the source of truth after going through language review.

Documentation modifications or augmentations are not part of this effort. Those kinds of changes are expected to be done directly in dotnet-api-docs, since that is the source of truth.

We will include APIs from Runtime Libraries (System and Microsoft.Extensions namespaces), WPF and WinForms.

Total undocumented APIs per repo + namespace

Runtime - System

System APIs	1.x	2.x	5.x	Total debt
S.Reflection	192	10		202
S.Reflection.PortableExecutable	135			135
S.Reflection.Emit	32	13		45
S.Security.Cryptography.Pkcs		18		18
S.Collections.Immutable	14			14
S.Formats.Cbor			5	5
S.Diagnostics	3	1		4
S.Linq	3			3
S.Security.Cryptography	1	2		3
S.ServiceModel.Channels	3			3
S.ComponentModel	2			2
S.Security.Permissions		2		2
S.Net	1			1
S.Net.Http		1		1
Total	386	47	5	438

Runtime - Microsoft.Extensions

Microsoft.Extensions APIs	1.x	2.x	3.x	5.x	Total debt
M.E.DependencyModel				113	113
M.E.Logging.Console	36	6		5	47
M.E.Logging	37	9			46
M.E.Caching.Memory	33	2			35
M.E.Primitives	23	10			33
M.E.DependencyInjection	18	9	1	2	30
M.E.Hosting		19	6		25
M.E.DependencyModel.Resolution				22	22
M.E.Caching.Distributed	16	1	1		18
M.E.DiagnosticAdapter	15	3			18
M.E.Options	4	13		1	18
M.E.Configuration	10	4	2		16
M.E.Logging.Abstractions	5	7		1	13
M.E.Logging.EventLog	12	1			13
M.E.Http.Logging		7		2	9
M.E.Caching.Redis	8				8
M.E.Hosting.Systemd			8		8
M.E.Caching.SqlServer	7				7
M.E.FileSystemGlobbing	7				7
M.E.FileSystemGlobbing.Abstractions	7				7
M.E.Hosting.WindowsServices			6		6
M.E.Http		6			6
M.E.Logging.Debug	5	1			6
M.E.Logging.TraceSource	5				5
M.E.Caching.StackExchangeRedis		4			4
M.E.Configuration.Xml	3		1		4
M.E.FileProviders	4				4
M.E.Configuration.Ini	2		1		3
M.E.Configuration.Json	2		1		3
M.E.Configuration.NewtonsoftJson			3		3
M.E.Logging.Configuration		3			3
M.E.Logging.EventSource			3		3
M.E.Configuration.CommandLine	2				2
M.E.Configuration.EnvironmentVariables	2				2
M.E.Configuration.Memory	2				2
M.E.Configuration.UserSecrets	2				2
M.E.DependencyInjection.Extensions	1	1			2
M.E.DiagnosticAdapter.Infrastructure	1				1
M.E.FileProviders.Composite	1				1
M.E.FileProviders.Physical	1				1
Total	271	106	33	146	556

WinForms

WinForms APIs	3.x	5.x	Total debt
System.Windows.Forms		73	73
System.Windows.Diagnostics		9	9
System.Windows.Markup		8	8
System.Windows.Forms.VisualStyles		1	1
Total	0	91	91

WPF

WPF APIs	3.x	Total debt
System.Xaml.Permissions	2	2
Total	2	2

Issues tracking debt per area

System

• API documentation debt - System.Collections #43850
• API documentation debt - System.ComponentModel #43852
• API documentation debt - System.Diagnostics #43860
• API documentation debt - System.Formats.Cbor #43858
• API documentation debt - System.Linq #43854
• API documentation debt - System.Net #43859
• API documentation debt - System.Reflection #43864
• API documentation debt - System.Security #43861
• API documentation debt - System.ServiceModel #43855

Microsoft.Extensions

• API documentation debt - Microsoft.Extensions.Caching #43868
• API documentation debt - Microsoft.Extensions.Configuration #43869
• API documentation debt - Microsoft.Extensions.DependencyInjection #43871
• API documentation debt - Microsoft.Extensions.DependencyModel #43872
• API documentation debt - Microsoft.Extensions.DiagnosticAdapter #43898
• API documentation debt - Microsoft.Extensions.FileProvider #43900
• API documentation debt - Microsoft.Extensions.FileSystemGlobbing #43908
• API documentation debt - Microsoft.Extensions.Hosting #43915
• API documentation debt - Microsoft.Extensions.Http #43916
• API documentation debt - Microsoft.Extensions.Logging #43918
• API documentation debt - Microsoft.Extensions.Options #43919
• API documentation debt - Microsoft.Extensions.Primitives #43920

WinForms

• API documentation debt - WinForms winforms#4163

WPF

• API documentation debt - WPF wpf#3708

[reflectronic]

There is a significant amount of missing documentation under System.Reflection.Metadata and System.Reflection.Metadata.Ecma335. I do not see these two namespaces tracked by this issue. I suppose that these APIs are not the most critical (and many of the missing members are simply things like implicit conversions with little to elaborate on), but is the progress being tracked anywhere for these?

[carlossanlop]

I suppose that these APIs are not the most critical

Correct, that is the main reason - These are advanced APIs, so we have not been considering them for documentation efforts.

The other reason is that their API surface is huge. Combined with the first reason, it does not make sense to spend so much time on these advanced APIs.

We made the same decision with System.Runtime.Intrinsics.

We will plan to address them at a later time.

This shouldn't stop user contributions though. If you feel like you have good knowledge on these APIs, feel free to document them.