Aspnetcore: Docs: Add summaries to ASP.NET Core namespaces

Created on 28 Oct 2020 · 3Comments · Source: dotnet/aspnetcore

ASP.NET Core namespaces don't have summary descriptions. Compare:

ASP.NET Core API Reference vs .NET API Reference.

Namespaces don't have /// comments, and so are documented in dotnet/AspNetApiDocs XML files. Namespace XML files aren't overwritten by doc sync.

Information about how to write a namespace summary: https://github.com/dotnet/dotnet-api-docs/wiki/Summary:-Namespace

There are 159 namespaces to do, so lots of work for everyone. I've tried to give people namespaces that they worked on or are familiar with. Search for your GitHub name in the browser to highlight your namespaces.

[x] Microsoft.AspNetCore Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Antiforgery Namespace | @pranavkm
[ ] Microsoft.AspNetCore.ApiAuthorization.IdentityServer Namespace | @pranavkm
[x] Microsoft.AspNetCore.Authentication Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.AzureAD.UI Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.AzureADB2C.UI Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Certificate Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Cookies Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Facebook Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Google Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.JwtBearer Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.MicrosoftAccount Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Negotiate Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.OAuth Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.OAuth.Claims Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.OpenIdConnect Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.OpenIdConnect.Claims Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.Twitter Namespace | @HaoK
[x] Microsoft.AspNetCore.Authentication.WsFederation Namespace | @HaoK
[x] Microsoft.AspNetCore.Authorization Namespace | @HaoK
[x] Microsoft.AspNetCore.Authorization.Infrastructure Namespace | @HaoK
[x] Microsoft.AspNetCore.Authorization.Policy Namespace | @HaoK
[x] Microsoft.AspNetCore.AzureAppServices.HostingStartup Namespace | @JamesNK
[x] Microsoft.AspNetCore.Builder Namespace | @BrennanConroy
[x] Microsoft.AspNetCore.Builder.Extensions Namespace | @BrennanConroy
[x] Microsoft.AspNetCore.Components Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Authorization Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.CompilerServices Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Forms Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.RenderTree Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Rendering Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Routing Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Server Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Server.Circuits Namespace | @captainsafia
[x] Microsoft.AspNetCore.Components.Web Namespace | @captainsafia
[x] Microsoft.AspNetCore.ConcurrencyLimiter Namespace | @BrennanConroy
[x] Microsoft.AspNetCore.Connections Namespace | @BrennanConroy
[x] Microsoft.AspNetCore.Connections.Features Namespace | @BrennanConroy
[ ] Microsoft.AspNetCore.CookiePolicy Namespace | @wtgodbe
[ ] Microsoft.AspNetCore.Cors Namespace | @wtgodbe
[ ] Microsoft.AspNetCore.Cors.Infrastructure Namespace | @wtgodbe
[x] Microsoft.AspNetCore.Cryptography.KeyDerivation Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.EntityFrameworkCore Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.Infrastructure Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.KeyManagement Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.Repositories Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.StackExchangeRedis Namespace | @jkotalik
[x] Microsoft.AspNetCore.DataProtection.XmlEncryption Namespace | @jkotalik
[x] Microsoft.AspNetCore.Diagnostics Namespace | @JamesNK
[x] Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore Namespace | @JamesNK
[x] Microsoft.AspNetCore.Diagnostics.HealthChecks Namespace | @JamesNK
[ ] Microsoft.AspNetCore.HeaderPropagation Namespace | @Tratcher
[ ] Microsoft.AspNetCore.HostFiltering Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.Builder Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.Server Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.Server.Abstractions Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.Server.Features Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.StaticWebAssets Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Hosting.WindowsServices Namespace | @Tratcher
[x] Microsoft.AspNetCore.Html Namespace | @halter73
[x] Microsoft.AspNetCore.Http Namespace | @halter73
[x] Microsoft.AspNetCore.Http.Connections Namespace | @halter73
[x] Microsoft.AspNetCore.Http.Connections.Features Namespace | @halter73
[x] Microsoft.AspNetCore.Http.Extensions Namespace | @halter73
[x] Microsoft.AspNetCore.Http.Features Namespace | @halter73
[x] Microsoft.AspNetCore.Http.Features.Authentication Namespace | @halter73
[ ] Microsoft.AspNetCore.Http.Headers Namespace | @wtgodbe
[ ] Microsoft.AspNetCore.HttpOverrides Namespace | @wtgodbe
[ ] Microsoft.AspNetCore.HttpsPolicy Namespace | @wtgodbe
[ ] Microsoft.AspNetCore.Identity Namespace | @javiercn
[ ] Microsoft.AspNetCore.Identity.EntityFrameworkCore Namespace | @javiercn
[ ] Microsoft.AspNetCore.Identity.UI Namespace | @javiercn
[ ] Microsoft.AspNetCore.Identity.UI.Services Namespace | @javiercn
[ ] Microsoft.AspNetCore.JsonPatch Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.JsonPatch.Adapters Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.JsonPatch.Converters Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.JsonPatch.Exceptions Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.JsonPatch.Helpers Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.JsonPatch.Operations Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.Localization Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.Localization.Routing Namespace | @ryanbrandenburg
[ ] Microsoft.AspNetCore.MiddlewareAnalysis Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.Abstractions Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.ActionConstraints Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.ApiExplorer Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.ApplicationModels Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.ApplicationParts Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.Authorization Namespace | @javiercn
[ ] Microsoft.AspNetCore.Mvc.Controllers Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.Core.Infrastructure Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.Cors Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.DataAnnotations Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.Diagnostics Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.Filters Namespace | @pranavkm
[ ] Microsoft.AspNetCore.Mvc.Formatters Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.Formatters.Xml Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.Infrastructure Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.Localization Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.ModelBinding Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.ModelBinding.Binders Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.ModelBinding.Metadata Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.ModelBinding.Validation Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.NewtonsoftJson Namespace | @dougbu
[ ] Microsoft.AspNetCore.Mvc.Razor Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Razor.Compilation Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Razor.Infrastructure Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Razor.TagHelpers Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.RazorPages Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Rendering Namespace | @TanayParikh
[ ] Microsoft.AspNetCore.Mvc.Routing Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.TagHelpers Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.Testing Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.Testing.Handlers Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.ViewComponents Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.ViewEngines Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.ViewFeatures Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.ViewFeatures.Buffers Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Mvc.ViewFeatures.Infrastructure Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Owin Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Razor.Hosting Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Razor.Runtime.TagHelpers Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.Razor.TagHelpers Namespace | @ajaybhargavb
[ ] Microsoft.AspNetCore.ResponseCaching Namespace | @Tratcher
[ ] Microsoft.AspNetCore.ResponseCompression Namespace | @Tratcher
[ ] Microsoft.AspNetCore.Rewrite Namespace | @Tratcher
[x] Microsoft.AspNetCore.Routing Namespace | @JamesNK
[x] Microsoft.AspNetCore.Routing.Constraints Namespace | @JamesNK
[x] Microsoft.AspNetCore.Routing.Matching Namespace | @JamesNK
[x] Microsoft.AspNetCore.Routing.Patterns Namespace | @JamesNK
[x] Microsoft.AspNetCore.Routing.Template Namespace | @JamesNK
[x] Microsoft.AspNetCore.Routing.Tree Namespace | @JamesNK
[x] Microsoft.AspNetCore.Server.HttpSys Namespace | @jkotalik
[x] Microsoft.AspNetCore.Server.IIS Namespace | @jkotalik
[x] Microsoft.AspNetCore.Server.IIS.Core Namespace | @jkotalik
[x] Microsoft.AspNetCore.Server.IISIntegration Namespace | @jkotalik
[ ] Microsoft.AspNetCore.Server.Kestrel Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Core Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Core.Features Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Https Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Transport.Experimental.Quic Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets Namespace | @sebastienros
[ ] Microsoft.AspNetCore.Session Namespace | @JunTaoLuo
[x] Microsoft.AspNetCore.SignalR Namespace | @BrennanConroy
[x] Microsoft.AspNetCore.SignalR.Protocol Namespace | @BrennanConroy
[ ] Microsoft.AspNetCore.StaticFiles Namespace | @JunTaoLuo
[ ] Microsoft.AspNetCore.StaticFiles.Infrastructure Namespace | @JunTaoLuo
[ ] Microsoft.AspNetCore.TestHost Namespace | @JunTaoLuo
[ ] Microsoft.AspNetCore.WebSockets Namespace | @JunTaoLuo
[ ] Microsoft.AspNetCore.WebUtilities Namespace | @JunTaoLuo
[ ] Microsoft.JSInterop Namespace | @SteveSandersonMS
[ ] Microsoft.JSInterop.Infrastructure Namespace | @SteveSandersonMS
[ ] Microsoft.Net.Http.Headers Namespace | @JunTaoLuo

Docs area-platform

Source

JamesNK

Most helpful comment

Example PR for adding namespace summary: https://github.com/dotnet/AspNetApiDocs/pull/168

Scale how detailed the summary is based on the namespace. One sentence is fine for most. More popular or complex namespaces can be up to a paragraph. Also, remarks can be used to link to relevent conceptual articles.

Note: remove /en-us/ and version number from conceptual article URLs. That allows the site to redirect the browser to the best language/version for them.

JamesNK on 28 Oct 2020

👍3

All 3 comments

Example PR for adding namespace summary: https://github.com/dotnet/AspNetApiDocs/pull/168

Note: remove /en-us/ and version number from conceptual article URLs. That allows the site to redirect the browser to the best language/version for them.

JamesNK on 28 Oct 2020

👍3

@JamesNK the examples you sited are for the 5.0 docs. Which branch should we target in our docs PRs to get the changes into those views❔