Add docs for Authentication.Abstractions (#26438)

* Add docs for Authentication.Abstractions

Contributes to https://github.com/dotnet/aspnetcore/issues/26397

* Turn on docs warning for Authentication.Core

* Update src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs

* Update src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs

src/Http/Authentication.Abstractions/src/AuthenticationHttpContextExtensions.cs

@@ -14,7 +14,8 @@ namespace Microsoft.AspNetCore.Authentication
     public static class AuthenticationHttpContextExtensions
     {
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/> scheme.
+        /// Authenticate the current request using the default authentication scheme.
+        /// The default authentication scheme can be configured using <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The <see cref="AuthenticateResult"/>.</returns>
@@ -22,7 +23,7 @@ namespace Microsoft.AspNetCore.Authentication
             context.AuthenticateAsync(scheme: null);
 
         /// <summary>
-        /// Extension method for authenticate.
+        /// Authenticate the current request using the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -31,7 +32,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.RequestServices.GetRequiredService<IAuthenticationService>().AuthenticateAsync(context, scheme);
 
         /// <summary>
-        /// Extension method for Challenge.
+        /// Challenge the current request using the specified scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -40,7 +42,9 @@ namespace Microsoft.AspNetCore.Authentication
             context.ChallengeAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultChallengeScheme"/> scheme.
+        /// Challenge the current request using the default challenge scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
+        /// The default challenge scheme can be configured using <see cref="AuthenticationOptions.DefaultChallengeScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
@@ -48,7 +52,9 @@ namespace Microsoft.AspNetCore.Authentication
             context.ChallengeAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultChallengeScheme"/> scheme.
+        /// Challenge the current request using the default challenge scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
+        /// The default challenge scheme can be configured using <see cref="AuthenticationOptions.DefaultChallengeScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
@@ -57,7 +63,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.ChallengeAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for Challenge.
+        /// Challenge the current request using the specified scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -67,7 +74,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.RequestServices.GetRequiredService<IAuthenticationService>().ChallengeAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the specified scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -76,7 +84,9 @@ namespace Microsoft.AspNetCore.Authentication
             context.ForbidAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for Forbid using the <see cref="AuthenticationOptions.DefaultForbidScheme"/> scheme..
+        /// Forbid the current request using the default forbid scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
+        /// The default forbid scheme can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
@@ -84,7 +94,9 @@ namespace Microsoft.AspNetCore.Authentication
             context.ForbidAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the default forbid scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
+        /// The default forbid scheme can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
@@ -93,7 +105,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.ForbidAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for Forbid.
+        /// Forbid the current request using the specified scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -103,7 +116,7 @@ namespace Microsoft.AspNetCore.Authentication
             context.RequestServices.GetRequiredService<IAuthenticationService>().ForbidAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for SignIn.
+        /// Sign in a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -113,7 +126,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.SignInAsync(scheme, principal, properties: null);
 
         /// <summary>
-        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// Sign in a principal for the default authentication scheme.
+        /// The default scheme for signing in can be configured using <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="principal">The user.</param>
@@ -122,7 +136,8 @@ namespace Microsoft.AspNetCore.Authentication
             context.SignInAsync(scheme: null, principal: principal, properties: null);
 
         /// <summary>
-        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// Sign in a principal for the default authentication scheme.
+        /// The default scheme for signing in can be configured using <see cref="AuthenticationOptions.DefaultForbidScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="principal">The user.</param>
@@ -132,7 +147,7 @@ namespace Microsoft.AspNetCore.Authentication
             context.SignInAsync(scheme: null, principal: principal, properties: properties);
 
         /// <summary>
-        /// Extension method for SignIn.
+        /// Sign in a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -143,14 +158,16 @@ namespace Microsoft.AspNetCore.Authentication
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignInAsync(context, scheme, principal, properties);
 
         /// <summary>
-        /// Extension method for SignOut using the <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
+        /// Sign out a principal for the default authentication scheme.
+        /// The default scheme for signing out can be configured using <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <returns>The task.</returns>
         public static Task SignOutAsync(this HttpContext context) => context.SignOutAsync(scheme: null, properties: null);
 
         /// <summary>
-        /// Extension method for SignOut using the <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
+        /// Sign out a principal for the default authentication scheme.
+        /// The default scheme for signing out can be configured using <see cref="AuthenticationOptions.DefaultSignOutScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
@@ -158,7 +175,7 @@ namespace Microsoft.AspNetCore.Authentication
         public static Task SignOutAsync(this HttpContext context, AuthenticationProperties? properties) => context.SignOutAsync(scheme: null, properties: properties);
 
         /// <summary>
-        /// Extension method for SignOut.
+        /// Sign out a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -166,7 +183,7 @@ namespace Microsoft.AspNetCore.Authentication
         public static Task SignOutAsync(this HttpContext context, string? scheme) => context.SignOutAsync(scheme, properties: null);
 
         /// <summary>
-        /// Extension method for SignOut.
+        /// Sign out a principal for the specified scheme.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -176,21 +193,22 @@ namespace Microsoft.AspNetCore.Authentication
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignOutAsync(context, scheme, properties);
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the specified scheme and returns the value for the token.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static Task<string?> GetTokenAsync(this HttpContext context, string? scheme, string tokenName) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, scheme, tokenName);
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the default authentication scheme and returns the value for the token.
+        /// The default authentication scheme can be configured using <see cref="AuthenticationOptions.DefaultAuthenticateScheme"/>.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static Task<string?> GetTokenAsync(this HttpContext context, string tokenName) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, tokenName);
     }

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

@@ -9,6 +9,9 @@ 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>();
@@ -93,7 +96,8 @@ namespace Microsoft.AspNetCore.Authentication
         public string? DefaultForbidScheme { get; set; }
 
         /// <summary>
-        /// If true, SignIn should throw if attempted with a ClaimsPrincipal.Identity.IsAuthenticated = false.
+        /// If true, SignIn should throw if attempted with a user is not authenticated.
+        /// A user is considered authenticated if <see cref="ClaimsIdentity.IsAuthenticated"/> returns <see langword="true" /> for the <see cref="ClaimsPrincipal"/> associated with the HTTP request.
         /// </summary>
         public bool RequireAuthenticatedSignIn { get; set; } = true;
     }

src/Http/Authentication.Abstractions/src/AuthenticationProperties.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 
 namespace Microsoft.AspNetCore.Authentication
@@ -122,10 +121,10 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Set a string value in the <see cref="Items"/> collection.
+        /// Set or remove a string value from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         public void SetString(string key, string? value)
         {
             if (value != null)
@@ -157,10 +156,10 @@ namespace Microsoft.AspNetCore.Authentication
             => Parameters[key] = value;
 
         /// <summary>
-        /// Get a bool value from the <see cref="Items"/> collection.
+        /// Get a nullable <see cref="bool"/> from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <returns>Retrieved value or <c>null</c> if the property is not set.</returns>
+        /// <returns>Retrieved value or <see langword="null" /> if the property is not set.</returns>
         protected bool? GetBool(string key)
         {
             if (Items.TryGetValue(key, out var value) && bool.TryParse(value, out var boolValue))
@@ -171,10 +170,10 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Set a bool value in the <see cref="Items"/> collection.
+        /// Set or remove a <see cref="bool"/> value in the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         protected void SetBool(string key, bool? value)
         {
             if (value.HasValue)
@@ -188,10 +187,10 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Get a DateTimeOffset value from the <see cref="Items"/> collection.
+        /// Get a nullable <see cref="DateTimeOffset"/> value from the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <returns>Retrieved value or <c>null</c> if the property is not set.</returns>
+        /// <returns>Retrieved value or <see langword="null" /> if the property is not set.</returns>
         protected DateTimeOffset? GetDateTimeOffset(string key)
         {
             if (Items.TryGetValue(key, out var value)
@@ -203,10 +202,10 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Set a DateTimeOffset value in the <see cref="Items"/> collection.
+        /// Sets or removes a <see cref="DateTimeOffset" /> value in the <see cref="Items"/> collection.
         /// </summary>
         /// <param name="key">Property key.</param>
-        /// <param name="value">Value to set or <c>null</c> to remove the property.</param>
+        /// <param name="value">Value to set or <see langword="null" /> to remove the property.</param>
         protected void SetDateTimeOffset(string key, DateTimeOffset? value)
         {
             if (value.HasValue)

src/Http/Authentication.Abstractions/src/AuthenticationScheme.cs

@@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Authentication
     public class AuthenticationScheme
     {
         /// <summary>
-        /// Constructor.
+        /// Initializes a new instance of <see cref="AuthenticationScheme"/>.
         /// </summary>
         /// <param name="name">The name for the authentication scheme.</param>
         /// <param name="displayName">The display name for the authentication scheme.</param>

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

@@ -21,17 +21,17 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// The name of the scheme being built.
+        /// Gets the name of the scheme being built.
         /// </summary>
         public string Name { get; }
 
         /// <summary>
-        /// The display name for the scheme being built.
+        /// Gets or sets the display name for the scheme being built.
         /// </summary>
         public string? DisplayName { get; set; }
 
         /// <summary>
-        /// The <see cref="IAuthenticationHandler"/> type responsible for this scheme.
+        /// Gets or sets the <see cref="IAuthenticationHandler"/> type responsible for this scheme.
         /// </summary>
         [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
         public Type? HandlerType { get; set; }
@@ -39,7 +39,7 @@ namespace Microsoft.AspNetCore.Authentication
         /// <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/AuthenticationTicket.cs

@@ -16,7 +16,7 @@ namespace Microsoft.AspNetCore.Authentication
         /// </summary>
         /// <param name="principal">the <see cref="ClaimsPrincipal"/> that represents the authenticated user.</param>
         /// <param name="properties">additional properties that can be consumed by the user or runtime.</param>
-        /// <param name="authenticationScheme">the authentication middleware that was responsible for this ticket.</param>
+        /// <param name="authenticationScheme">the authentication scheme that was responsible for this ticket.</param>
         public AuthenticationTicket(ClaimsPrincipal principal, AuthenticationProperties? properties, string authenticationScheme)
         {
             if (principal == null)
@@ -33,13 +33,13 @@ namespace Microsoft.AspNetCore.Authentication
         /// Initializes a new instance of the <see cref="AuthenticationTicket"/> class
         /// </summary>
         /// <param name="principal">the <see cref="ClaimsPrincipal"/> that represents the authenticated user.</param>
-        /// <param name="authenticationScheme">the authentication middleware that was responsible for this ticket.</param>
+        /// <param name="authenticationScheme">the authentication scheme that was responsible for this ticket.</param>
         public AuthenticationTicket(ClaimsPrincipal principal, string authenticationScheme) 
             : this(principal, properties: null, authenticationScheme: authenticationScheme)
         { }
 
         /// <summary>
-        /// Gets the authentication type.
+        /// Gets the authentication scheme that was responsible for this ticket.
         /// </summary>
         public string AuthenticationScheme { get; }
 
@@ -55,8 +55,10 @@ namespace Microsoft.AspNetCore.Authentication
 
         /// <summary>
         /// Returns a copy of the ticket.
-        /// Note: the claims principal will be cloned by calling Clone() on each of the Identities.
         /// </summary>
+        /// <remarks>
+        /// The method clones the <see cref="Principal"/> by calling <see cref="ClaimsIdentity.Clone"/> on each of the <see cref="ClaimsPrincipal.Identities"/>.
+        /// </remarks>
         /// <returns>A copy of the ticket</returns>
         public AuthenticationTicket Clone()
         {

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

@@ -12,31 +12,28 @@ namespace Microsoft.AspNetCore.Authentication
     public interface IAuthenticationHandler
     {
         /// <summary>
-        /// The handler should initialize anything it needs from the request and scheme here.
+        /// Initialize the authentication handler. The handler should initialize anything it needs from the request and scheme as part of this method.
         /// </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>
-        /// Authentication behavior.
+        /// Authenticate the current request.
         /// </summary>
         /// <returns>The <see cref="AuthenticateResult"/> result.</returns>
         Task<AuthenticateResult> AuthenticateAsync();
 
         /// <summary>
-        /// Challenge behavior.
+        /// Challenge the current request.
         /// </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.
+        /// Forbid the current request.
         /// </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.Abstractions/src/IAuthenticationHandlerProvider.cs

@@ -14,7 +14,7 @@ namespace Microsoft.AspNetCore.Authentication
         /// <summary>
         /// Returns the handler instance that will be used.
         /// </summary>
-        /// <param name="context">The context.</param>
+        /// <param name="context">The <see cref="HttpContext"/>.</param>
         /// <param name="authenticationScheme">The name of the authentication scheme being handled.</param>
         /// <returns>The handler instance.</returns>
         Task<IAuthenticationHandler?> GetHandlerAsync(HttpContext context, string authenticationScheme);

src/Http/Authentication.Abstractions/src/IAuthenticationRequestHandler.cs

@@ -11,7 +11,12 @@ namespace Microsoft.AspNetCore.Authentication
     public interface IAuthenticationRequestHandler : IAuthenticationHandler
     {
         /// <summary>
-        /// Returns true if request processing should stop.
+        /// Gets a value that determines if the request should stop being processed.
+        /// <para>
+        /// This feature is supported by the Authentication middleware
+        /// which does not invoke any subsequent <see cref="IAuthenticationHandler"/> or middleware configured in the request pipeline
+        /// if the handler returns <see langword="true" />.
+        /// </para>
         /// </summary>
         /// <returns><see langword="true" /> if request processing should stop.</returns>
         Task<bool> HandleRequestAsync();

src/Http/Authentication.Abstractions/src/IAuthenticationService.cs

@@ -22,6 +22,7 @@ namespace Microsoft.AspNetCore.Authentication
 
         /// <summary>
         /// Challenge the specified authentication scheme.
+        /// An authentication challenge can be issued when an unauthenticated user requests an endpoint that requires authentication.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/>.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
@@ -31,6 +32,7 @@ namespace Microsoft.AspNetCore.Authentication
 
         /// <summary>
         /// Forbids the specified authentication scheme.
+        /// Forbid is used when an authenticated user attempts to access a resource they are not permitted to access.
         /// </summary>
         /// <param name="context">The <see cref="HttpContext"/>.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>

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

@@ -3,7 +3,7 @@
     <Description>ASP.NET Core common types used by the various authentication 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/Authentication.Abstractions/src/TokenExtensions.cs

@@ -80,6 +80,13 @@ namespace Microsoft.AspNetCore.Authentication
             return properties.Items.TryGetValue(tokenKey, out var value) ? value : null;
         }
 
+        /// <summary>
+        /// Updates the value of a token if already present.
+        /// </summary>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> to update.</param>
+        /// <param name="tokenName">The token name.</param>
+        /// <param name="tokenValue">The token value.</param>
+        /// <returns><see langword="true"/> if the token was updated, otherwise <see langword="false"/>.</returns>
         public static bool UpdateTokenValue(this AuthenticationProperties properties, string tokenName, string tokenValue)
         {
             if (properties == null)
@@ -101,7 +108,7 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Returns all of the AuthenticationTokens contained in the properties.
+        /// Returns all of the <see cref="AuthenticationToken"/> instances contained in the properties.
         /// </summary>
         /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
         /// <returns>The authentication tokens.</returns>
@@ -130,23 +137,23 @@ namespace Microsoft.AspNetCore.Authentication
         }
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the specified authentication scheme and returns the value for the token.
         /// </summary>
         /// <param name="auth">The <see cref="IAuthenticationService"/>.</param>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static Task<string?> GetTokenAsync(this IAuthenticationService auth, HttpContext context, string tokenName)
             => auth.GetTokenAsync(context, scheme: null, tokenName: tokenName);
 
         /// <summary>
-        /// Extension method for getting the value of an authentication token.
+        /// Authenticates the request using the specified authentication scheme and returns the value for the token.
         /// </summary>
         /// <param name="auth">The <see cref="IAuthenticationService"/>.</param>
         /// <param name="context">The <see cref="HttpContext"/> context.</param>
         /// <param name="scheme">The name of the authentication scheme.</param>
         /// <param name="tokenName">The name of the token.</param>
-        /// <returns>The value of the token.</returns>
+        /// <returns>The value of the token if present.</returns>
         public static async Task<string?> GetTokenAsync(this IAuthenticationService auth, HttpContext context, string? scheme, string tokenName)
         {
             if (auth == null)

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

@@ -201,6 +201,7 @@ namespace Microsoft.AspNetCore.Authentication
             }
         }
 
+        /// <inheritdoc />
         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>