API ref docs

[pranavkm]

This issue tracks filling in the blanks in our API ref docs. We'd like to make sure all public API surface in our types are documented and that we're able to enable the doc warning CS1591 in our projects.

Later this week, we'll follow up on doing a pass on APIs that are commonly used by project templates and user code to figure out if we need expand on the documentation coverage there or if the language can be simplified. We want to incorporate more of our concept docs too if it is helpful. Feel free to do an initial pass on areas that you're working on to also cover this.

• Hosting, Http Abstractions, Routing (@captainsafia)
• Servers
  • IIS (@jkotalik)
  • Kestrel (@javiercn)
  • HttpSys (@wtgodbe)
• Middleware
  • Static files, HttpsPolicy, Diagnostics, HostFiltering, ResponseCaching, HttpOverrides (@JunTaoLuo)
  • Localization, Localization.Routing, ResponseCompression (@SteveSandersonMS)
  • WebSockets (@BrennanConroy)
  • HealthChecks, CORS (@JamesNK)
  • Session, Diagnostics.EntityFrameworkCore, MiddlewareAnalysis, , HeaderPropagation, NodeServices (@halter73)
  • Rewrite (@jkotalik)
• Security - Authentication, CookiePolicy (@pranavkm)
• MVC
• Components (@HaoK)
• SignalR (@BrennanConroy)
• Identity, IdentityUI (@HaoK)

Once a project has 100% doc coverage, consider enabling warnings for missing docs by adding this to your project file:

<NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>

[HaoK]

@pranavkm just double checking in case we supposed to be swapped MVC/Components for you and Security/Auth for me?

[halter73]

I'm still working on some last-minute 5.0 fixes. I wonder if it wouldn't make more sense for me to take Kestrel and someone else to take "Session, Diagnostics.EntityFrameworkCore, MiddlewareAnalysis, , HeaderPropagation, NodeServices", but I can still do a first draft for those API docs.

[pranavkm]

wonder if it wouldn't make more sense for me to take Kestrel and someone else to take "Session, Diagnostics.EntityFrameworkCore, MiddlewareAnalysis, , HeaderPropagation, NodeServices",

Sure, if you feel you'd be more productive that way. I've been trying to mix things up to see if we can benefit from getting a secondary perspective authoring the content while the area owner reviews the content.

[jkotalik]

@pranavkm @SteveSandersonMS @javiercn will you all be able to handle these API docs soon?

[SteveSandersonMS]

@jkotalik Yes, submitted #26889

[javiercn]

@pranavkm this is done now

[dougbu]

@javiercn, @JunTaoLuo, and @pranavkm does this mean we can remove the $(NoWarn) setting for CS1591 errors and get rid of <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn> overrides❔

[JamesNK]

We should explore inverting it so there is no CS1591 in NoWarn by default. Remove CS1591 from top-level msbuild NoWarn and remove the NoWarn overrides. There will be projects where it needs to be added back (e.g. all test projects)

[pranavkm]

The NoWarn we have in the project files was to workaround an Arcade default: https://github.com/dotnet/arcade/blob/4873d157a8f34f8cc7e28b3f9938b32c642ef542/src/Microsoft.DotNet.Arcade.Sdk/tools/ProjectDefaults.props#L94. We could follow @JamesNK suggestion and apply the workaround by default while letting individual projects undo it. Filed #27106 to track this.

[dougbu]

1. We also have the following making 1591 a non-error:
   

   aspnetcore/Directory.Build.props

   Line 97 in da7fead

   <WarningsNotAsErrors>$(WarningsNotAsErrors);CS1591</WarningsNotAsErrors>

2. We already had Make doc comments required on public APIs #12067. I therefore closed Consider enabling CS1591 in AspNetCore by default for src projects #27106.