API docs for HttpAbstractions

src/Http/Authentication.Abstractions/src/AuthenticationOptions.cs

@@ -4,22 +4,24 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
-using System.Security.Claims;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Options to configure authentication.
+    /// </summary>
     public class AuthenticationOptions
     {
         private readonly IList<AuthenticationSchemeBuilder> _schemes = new List<AuthenticationSchemeBuilder>();
 
         /// <summary>
-        /// Returns the schemes in the order they were added (important for request handling priority)
+        /// Gets the schemes in the order they were added (important for request handling priority)
         /// </summary>
         public IEnumerable<AuthenticationSchemeBuilder> Schemes => _schemes;
 
         /// <summary>
-        /// Maps schemes by name.
+        /// Gets a mapping of names to authentication schemes.
         /// </summary>
         public IDictionary<string, AuthenticationSchemeBuilder> SchemeMap { get; } = new Dictionary<string, AuthenticationSchemeBuilder>(StringComparer.Ordinal);
 

src/Http/Authentication.Abstractions/src/AuthenticationSchemeBuilder.cs

@@ -39,7 +39,7 @@ public AuthenticationSchemeBuilder(string name)
         /// <summary>
         /// Builds the <see cref="AuthenticationScheme"/> instance.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>The <see cref="AuthenticationScheme"/>.</returns>
         public AuthenticationScheme Build()
         {
             if (HandlerType is null)

src/Http/Authentication.Abstractions/src/IAuthenticationHandler.cs

@@ -16,7 +16,6 @@ public interface IAuthenticationHandler
         /// </summary>
         /// <param name="scheme">The <see cref="AuthenticationScheme"/> scheme.</param>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
-        /// <returns></returns>
         Task InitializeAsync(AuthenticationScheme scheme, HttpContext context);
 
         /// <summary>
@@ -29,14 +28,12 @@ public interface IAuthenticationHandler
         /// Challenge behavior.
         /// </summary>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> that contains the extra meta-data arriving with the authentication.</param>
-        /// <returns>A task.</returns>
         Task ChallengeAsync(AuthenticationProperties? properties);
 
         /// <summary>
         /// Forbid behavior.
         /// </summary>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> that contains the extra meta-data arriving with the authentication.</param>
-        /// <returns>A task.</returns>
         Task ForbidAsync(AuthenticationProperties? properties);
     }
 }

src/Http/Authentication.Core/src/AuthenticationSchemeProvider.cs

@@ -201,6 +201,10 @@ public virtual void RemoveScheme(string name)
             }
         }
 
+        /// <summary>
+        /// Returns all currently registered <see cref="AuthenticationScheme"/> instances.
+        /// </summary>
+        /// <returns>All currently registered <see cref="AuthenticationScheme"/> instances.</returns>
         public virtual Task<IEnumerable<AuthenticationScheme>> GetAllSchemesAsync()
             => Task.FromResult(_schemesCopy);
     }

src/Http/Authentication.Core/src/Microsoft.AspNetCore.Authentication.Core.csproj

@@ -4,7 +4,7 @@
     <Description>ASP.NET Core common types used by the various authentication middleware components.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;authentication;security</PackageTags>
     <IsPackable>false</IsPackable>

src/Http/Http.Abstractions/src/ConnectionInfo.cs

@@ -8,23 +8,46 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Gets information about the current connection.
+    /// </summary>
     public abstract class ConnectionInfo
     {
         /// <summary>
         /// Gets or sets a unique identifier to represent this connection.
         /// </summary>
         public abstract string Id { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IPAddress"/> for the connecting client.
+        /// </summary>
         public abstract IPAddress? RemoteIpAddress { get; set; }
 
+        /// <summary>
+        /// Gets or sets the port for the connecting client.
+        /// </summary>
         public abstract int RemotePort { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IPAddress"/> for the host.
+        /// </summary>
         public abstract IPAddress? LocalIpAddress { get; set; }
 
+        /// <summary>
+        /// Gets or sets the port for the host.
+        /// </summary>
         public abstract int LocalPort { get; set; }
 
+        /// <summary>
+        /// Gets or sets the client certificate associated with the connection.
+        /// </summary>
         public abstract X509Certificate2? ClientCertificate { get; set; }
 
+        /// <summary>
+        /// Asynchronously retrieves the client certificate.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token to cancel operation.</param>
+        /// <returns>The client certificate if available.</returns>
         public abstract Task<X509Certificate2?> GetClientCertificateAsync(CancellationToken cancellationToken = new CancellationToken());
     }
 }

src/Http/Http.Abstractions/src/Extensions/HeaderDictionaryExtensions.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Extension methods for <see cref="IHeaderDictionary"/>.
+    /// </summary>
     public static class HeaderDictionaryExtensions
     {
         /// <summary>

src/Http/Http.Abstractions/src/Extensions/MapExtensions.cs

@@ -19,7 +19,7 @@ public static class MapExtensions
         /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="pathMatch">The request path to match.</param>
         /// <param name="configuration">The branch to take for positive path matches.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder Map(this IApplicationBuilder app, PathString pathMatch, Action<IApplicationBuilder> configuration)
         {
             return Map(app, pathMatch, preserveMatchedPathSegment: false, configuration);
@@ -33,7 +33,7 @@ public static IApplicationBuilder Map(this IApplicationBuilder app, PathString p
         /// <param name="pathMatch">The request path to match.</param>
         /// <param name="preserveMatchedPathSegment">if false, matched path would be removed from Request.Path and added to Request.PathBase.</param>
         /// <param name="configuration">The branch to take for positive path matches.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder Map(this IApplicationBuilder app, PathString pathMatch, bool preserveMatchedPathSegment, Action<IApplicationBuilder> configuration)
         {
             if (app == null)

src/Http/Http.Abstractions/src/Extensions/MapWhenExtensions.cs

@@ -18,10 +18,10 @@ public static class MapWhenExtensions
         /// <summary>
         /// Branches the request pipeline based on the result of the given predicate.
         /// </summary>
-        /// <param name="app"></param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/>.</param>
         /// <param name="predicate">Invoked with the request environment to determine if the branch should be taken</param>
         /// <param name="configuration">Configures a branch to take</param>
-        /// <returns></returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder MapWhen(this IApplicationBuilder app, Predicate predicate, Action<IApplicationBuilder> configuration)
         {
             if (app == null)
@@ -53,4 +53,4 @@ public static IApplicationBuilder MapWhen(this IApplicationBuilder app, Predicat
             return app.Use(next => new MapWhenMiddleware(next, options).Invoke);
         }
     }
-}
+}

src/Http/Http.Abstractions/src/Extensions/RequestTrailerExtensions.cs

@@ -16,8 +16,8 @@ public static class RequestTrailerExtensions
         /// <summary>
         /// Gets the request "Trailer" header that lists which trailers to expect after the body.
         /// </summary>
-        /// <param name="request"></param>
-        /// <returns></returns>
+        /// <param name="request">The <see cref="HttpRequest"/>.</param>
+        /// <returns>The request "Trailer" header.</returns>
         public static StringValues GetDeclaredTrailers(this HttpRequest request)
         {
             return request.Headers.GetCommaSeparatedValues(HeaderNames.Trailer);
@@ -26,8 +26,9 @@ public static StringValues GetDeclaredTrailers(this HttpRequest request)
         /// <summary>
         /// Indicates if the request supports receiving trailer headers.
         /// </summary>
-        /// <param name="request"></param>
-        /// <returns></returns>
+        /// <param name="request">The <see cref="HttpRequest"/>.</param>
+        /// <returns><see langword="true"/> if the request supports received trailer headers,
+        /// otherwise <see langword="false"/>.</returns>
         public static bool SupportsTrailers(this HttpRequest request)
         {
             return request.HttpContext.Features.Get<IHttpRequestTrailersFeature>() != null;
@@ -37,20 +38,22 @@ public static bool SupportsTrailers(this HttpRequest request)
         /// Checks if the request supports trailers and they are available to be read now.
         /// This does not mean that there are any trailers to read.
         /// </summary>
-        /// <param name="request"></param>
-        /// <returns></returns>
+        /// <param name="request">The <see cref="HttpRequest"/>.</param>
+        /// <returns><see langword="true"/> if the request supports trailer that are are available to be read,
+        /// otherwise <see langword="false"/>.</returns>
         public static bool CheckTrailersAvailable(this HttpRequest request)
         {
             return request.HttpContext.Features.Get<IHttpRequestTrailersFeature>()?.Available == true;
         }
 
         /// <summary>
         /// Gets the requested trailing header from the response. Check <see cref="SupportsTrailers"/>
-        /// or a NotSupportedException may be thrown.
+        /// or a <see cref="NotSupportedException"/> may be thrown.
         /// Check <see cref="CheckTrailersAvailable" /> or an InvalidOperationException may be thrown.
         /// </summary>
-        /// <param name="request"></param>
-        /// <param name="trailerName"></param>
+        /// <param name="request">The <see cref="HttpRequest"/>.</param>
+        /// <param name="trailerName">The trailer header to read.</param>
+        <returns>The requested trailed header value.</returns>
         public static StringValues GetTrailer(this HttpRequest request, string trailerName)
         {
             var feature = request.HttpContext.Features.Get<IHttpRequestTrailersFeature>();

src/Http/Http.Abstractions/src/Extensions/ResponseTrailerExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -8,13 +8,16 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Extension methods for <see cref="HttpResponse"/> to work with response trailer headers.
+    /// </summary>
     public static class ResponseTrailerExtensions
     {
         /// <summary>
         /// Adds the given trailer name to the 'Trailer' response header. This must happen before the response headers are sent.
         /// </summary>
-        /// <param name="response"></param>
-        /// <param name="trailerName"></param>
+        /// <param name="response">The <see cref="HttpResponse"/>.</param>
+        /// <param name="trailerName">The trailer name to add to the 'Trailer' response header</param>
         public static void DeclareTrailer(this HttpResponse response, string trailerName)
         {
             response.Headers.AppendCommaSeparatedValues(HeaderNames.Trailer, trailerName);
@@ -23,8 +26,9 @@ public static void DeclareTrailer(this HttpResponse response, string trailerName
         /// <summary>
         /// Indicates if the server supports sending trailer headers for this response.
         /// </summary>
-        /// <param name="response"></param>
-        /// <returns></returns>
+        /// <param name="response">The <see cref="HttpResponse"/>.</param>
+        /// <returns><see langword="true"/> if the server supports sending trailer headers for this response,
+        /// otherwise <see langword="false"/>.</returns>
         public static bool SupportsTrailers(this HttpResponse response)
         {
             var feature = response.HttpContext.Features.Get<IHttpResponseTrailersFeature>();
@@ -35,9 +39,9 @@ public static bool SupportsTrailers(this HttpResponse response)
         /// Adds the given trailer header to the trailers collection to be sent at the end of the response body.
         /// Check <see cref="SupportsTrailers" /> or an InvalidOperationException may be thrown.
         /// </summary>
-        /// <param name="response"></param>
-        /// <param name="trailerName"></param>
-        /// <param name="trailerValues"></param>
+        /// <param name="response">The <see cref="HttpResponse"/>.</param>
+        /// <param name="trailerName">The name of the trailer header.</param>
+        /// <param name="trailerValues">The trailer values to append.</param>
         public static void AppendTrailer(this HttpResponse response, string trailerName, StringValues trailerValues)
         {
             var feature = response.HttpContext.Features.Get<IHttpResponseTrailersFeature>();

src/Http/Http.Abstractions/src/Extensions/UseExtensions.cs

@@ -17,7 +17,7 @@ public static class UseExtensions
         /// </summary>
         /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="middleware">A function that handles the request or calls the given next function.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder Use(this IApplicationBuilder app, Func<HttpContext, Func<Task>, Task> middleware)
         {
             return app.Use(next =>

src/Http/Http.Abstractions/src/Extensions/UseMiddlewareExtensions.cs

@@ -32,7 +32,7 @@ public static class UseMiddlewareExtensions
         /// <typeparam name="TMiddleware">The middleware type.</typeparam>
         /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="args">The arguments to pass to the middleware type instance's constructor.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder UseMiddleware<[DynamicallyAccessedMembers(MiddlewareAccessibility)]TMiddleware>(this IApplicationBuilder app, params object[] args)
         {
             return app.UseMiddleware(typeof(TMiddleware), args);
@@ -44,7 +44,7 @@ public static class UseMiddlewareExtensions
         /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="middleware">The middleware type.</param>
         /// <param name="args">The arguments to pass to the middleware type instance's constructor.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder UseMiddleware(this IApplicationBuilder app, [DynamicallyAccessedMembers(MiddlewareAccessibility)] Type middleware, params object[] args)
         {
             if (typeof(IMiddleware).GetTypeInfo().IsAssignableFrom(middleware.GetTypeInfo()))

src/Http/Http.Abstractions/src/Extensions/UsePathBaseExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -17,7 +17,7 @@ public static class UsePathBaseExtensions
         /// </summary>
         /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="pathBase">The path base to extract.</param>
-        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder UsePathBase(this IApplicationBuilder app, PathString pathBase)
         {
             if (app == null)
@@ -35,4 +35,4 @@ public static IApplicationBuilder UsePathBase(this IApplicationBuilder app, Path
             return app.UseMiddleware<UsePathBaseMiddleware>(pathBase);
         }
     }
-}
+}

src/Http/Http.Abstractions/src/Extensions/UseWhenExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -16,10 +16,10 @@ public static class UseWhenExtensions
         /// <summary>
         /// Conditionally creates a branch in the request pipeline that is rejoined to the main pipeline.
         /// </summary>
-        /// <param name="app"></param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/>.</param>
         /// <param name="predicate">Invoked with the request environment to determine if the branch should be taken</param>
         /// <param name="configuration">Configures a branch to take</param>
-        /// <returns></returns>
+        /// <returns>A reference to the <paramref name="app"/> after the operation has completed.</returns>
         public static IApplicationBuilder UseWhen(this IApplicationBuilder app, Predicate predicate, Action<IApplicationBuilder> configuration)
         {
             if (app == null)
@@ -45,7 +45,7 @@ public static IApplicationBuilder UseWhen(this IApplicationBuilder app, Predicat
 
             return app.Use(main =>
             {
-                // This is called only when the main application builder 
+                // This is called only when the main application builder
                 // is built, not per request.
                 branchBuilder.Run(main);
                 var branch = branchBuilder.Build();
@@ -64,4 +64,4 @@ public static IApplicationBuilder UseWhen(this IApplicationBuilder app, Predicat
             });
         }
     }
-}
+}