Add doc comments

Author: HaoK

src/Microsoft.AspNetCore.Authentication.Abstractions/AuthenticateContext.cs

@@ -5,8 +5,16 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Base class used by <see cref="IAuthenticationHandler"/> methods.
+    /// </summary>
     public class AuthenticateContext : BaseAuthenticationContext
     {
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="authenticationScheme">The name of the authentication scheme.</param>
         public AuthenticateContext(HttpContext context, string authenticationScheme) : base(context, authenticationScheme, properties: null)
         { }
     }

src/Microsoft.AspNetCore.Authentication.Abstractions/AuthenticateResult.cs

@@ -16,21 +16,13 @@ private AuthenticateResult() { }
         /// <summary>
         /// If a ticket was produced, authenticate was successful.
         /// </summary>
-        public bool Succeeded
-        {
-            get
-            {
-                return Ticket != null;
-            }
-        }
+        public bool Succeeded => Ticket != null;
 
         /// <summary>
         /// The authentication ticket.
         /// </summary>
         public AuthenticationTicket Ticket { get; private set; }
 
-        // REVIEW: should we also remember AuthenticationScheme?
-
         /// <summary>
         /// Gets the claims-principal with authenticated user identities.
         /// </summary>
@@ -57,6 +49,11 @@ public bool Succeeded
         /// </summary>
         public bool Nothing { get; private set; }
 
+        /// <summary>
+        /// Indicates that authentication was successful.
+        /// </summary>
+        /// <param name="ticket">The ticket representing the authentication result.</param>
+        /// <returns>The result.</returns>
         public static AuthenticateResult Success(AuthenticationTicket ticket)
         {
             if (ticket == null)
@@ -66,25 +63,43 @@ public static AuthenticateResult Success(AuthenticationTicket ticket)
             return new AuthenticateResult() { Ticket = ticket };
         }
 
+        /// <summary>
+        /// Indicates that stage of authentication was directly handled by user intervention and no
+        /// further processing should be attempted.
+        /// </summary>
+        /// <returns>The result.</returns>
         public static AuthenticateResult Handle()
         {
             return new AuthenticateResult() { Handled = true };
         }
 
+        /// <summary>
+        /// Indicates that there was no information returned for this authentication scheme.
+        /// </summary>
+        /// <returns>The result.</returns>
         public static AuthenticateResult None()
         {
             return new AuthenticateResult() { Nothing = true };
         }
 
+        /// <summary>
+        /// Indicates that there was a failure during authentication.
+        /// </summary>
+        /// <param name="failure">The failure exception.</param>
+        /// <returns>The result.</returns>
         public static AuthenticateResult Fail(Exception failure)
         {
             return new AuthenticateResult() { Failure = failure };
         }
 
+        /// <summary>
+        /// Indicates that there was a failure during authentication.
+        /// </summary>
+        /// <param name="failureMessage">The failure message.</param>
+        /// <returns>The result.</returns>
         public static AuthenticateResult Fail(string failureMessage)
         {
             return new AuthenticateResult() { Failure = new Exception(failureMessage) };
         }
-
     }
 }

src/Microsoft.AspNetCore.Authentication.Abstractions/AuthenticationHttpContextExtensions.cs

@@ -4,55 +4,154 @@
 using System.Security.Claims;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Http;
-using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Extension methods to expose Authentication on HttpContext.
+    /// </summary>
     public static class AuthenticationHttpContextExtensions
     {
+        /// <summary>
+        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultAuthenticationScheme"/> scheme.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <returns>The <see cref="AuthenticateResult"/>.</returns>
         public static Task<AuthenticateResult> AuthenticateAsync(this HttpContext context) =>
             context.AuthenticateAsync(scheme: null);
 
+        /// <summary>
+        /// Extension method for authenticate.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <returns>The <see cref="AuthenticateResult"/>.</returns>
         public static Task<AuthenticateResult> AuthenticateAsync(this HttpContext context, string scheme) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().AuthenticateAsync(context, scheme);
 
+        /// <summary>
+        /// Extension method for Challenge.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <returns>The result.</returns>
         public static Task ChallengeAsync(this HttpContext context, string scheme) =>
             context.ChallengeAsync(scheme, properties: null);
 
+        /// <summary>
+        /// Extension method for authenticate using the <see cref="AuthenticationOptions.DefaultChallengeScheme"/> scheme.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <returns>The task.</returns>
         public static Task ChallengeAsync(this HttpContext context) =>
             context.ChallengeAsync(scheme: null, properties: null);
 
+        /// <summary>
+        /// Extension method for Challenge.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <returns>The task.</returns>
         public static Task ChallengeAsync(this HttpContext context, string scheme, AuthenticationProperties properties) =>
             context.ChallengeAsync(scheme, properties: properties, behavior: ChallengeBehavior.Automatic);
 
+        /// <summary>
+        /// Extension method for Challenge.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <param name="behavior">The <see cref="ChallengeBehavior"/> behavior.</param>
+        /// <returns>The task.</returns>
         public static Task ChallengeAsync(this HttpContext context, string scheme, AuthenticationProperties properties, ChallengeBehavior behavior) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().ChallengeAsync(context, scheme, properties, behavior);
 
+        /// <summary>
+        /// Extension method for Forbid.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <returns>The task.</returns>
         public static Task ForbidAsync(this HttpContext context, string scheme) =>
             context.ForbidAsync(scheme, properties: null);
 
+        /// <summary>
+        /// Extension method for Forbid.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <returns>The task.</returns>
         public static Task ForbidAsync(this HttpContext context, string scheme, AuthenticationProperties properties) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().ChallengeAsync(context, scheme, properties, ChallengeBehavior.Forbidden);
 
+        /// <summary>
+        /// Extension method for SignIn.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="principal">The user.</param>
+        /// <returns>The task.</returns>
         public static Task SignInAsync(this HttpContext context, string scheme, ClaimsPrincipal principal) =>
             context.SignInAsync(scheme, principal, properties: null);
 
+        /// <summary>
+        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="principal">The user.</param>
+        /// <returns>The task.</returns>
         public static Task SignInAsync(this HttpContext context, ClaimsPrincipal principal) =>
             context.SignInAsync(scheme: null, principal: principal, properties: null);
 
+        /// <summary>
+        /// Extension method for SignIn using the <see cref="AuthenticationOptions.DefaultSignInScheme"/>.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="principal">The user.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <returns>The task.</returns>
         public static Task SignInAsync(this HttpContext context, ClaimsPrincipal principal, AuthenticationProperties properties) =>
             context.SignInAsync(scheme: null, principal: principal, properties: properties);
 
+        /// <summary>
+        /// Extension method for SignIn.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="principal">The user.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <returns>The task.</returns>
         public static Task SignInAsync(this HttpContext context, string scheme, ClaimsPrincipal principal, AuthenticationProperties properties) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignInAsync(context, scheme, principal, properties);
 
-
+        /// <summary>
+        /// Extension method for SignOut.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <returns>The task.</returns>
         public static Task SignOutAsync(this HttpContext context, string scheme) => context.SignOutAsync(scheme, properties: null);
 
+        /// <summary>
+        /// Extension method for SignOut.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> context.</param>
+        /// <param name="scheme">The name of the authentication scheme.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> properties.</param>
+        /// <returns></returns>
         public static Task SignOutAsync(this HttpContext context, string scheme, AuthenticationProperties properties) =>
             context.RequestServices.GetRequiredService<IAuthenticationService>().SignOutAsync(context, scheme, properties);
 
-        public static Task<string> GetTokenAsync(this HttpContext context, string signInScheme, string tokenName) =>
-            context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, signInScheme, tokenName);
+        /// <summary>
+        /// Extension method for getting the value of an authentication 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>
+        public static Task<string> GetTokenAsync(this HttpContext context, string scheme, string tokenName) =>
+            context.RequestServices.GetRequiredService<IAuthenticationService>().GetTokenAsync(context, scheme, tokenName);
     }
 }

src/Microsoft.AspNetCore.Authentication.Abstractions/AuthenticationSchemeBuilder.cs

@@ -5,17 +5,34 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Used to build <see cref="AuthenticationScheme"/>s.
+    /// </summary>
     public class AuthenticationSchemeBuilder
     {
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="name">The name of the scheme being built.</param>
         public AuthenticationSchemeBuilder(string name)
         {
             Name = name;
         }
 
+        /// <summary>
+        /// The name of the scheme being built.
+        /// </summary>
         public string Name { get; }
 
+        /// <summary>
+        /// The <see cref="IAuthenticationHandler"/> type responsible for this scheme.
+        /// </summary>
         public Type HandlerType { get; set; }
 
+        /// <summary>
+        /// Builds the <see cref="AuthenticationScheme"/> instance.
+        /// </summary>
+        /// <returns></returns>
         public AuthenticationScheme Build() => new AuthenticationScheme(Name, HandlerType);
     }
 }

src/Microsoft.AspNetCore.Authentication.Abstractions/AuthenticationToken.cs

@@ -4,9 +4,19 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Name/Value representing an token.
+    /// </summary>
     public class AuthenticationToken
     {
+        /// <summary>
+        /// Name.
+        /// </summary>
         public string Name { get; set; }
+
+        /// <summary>
+        /// Value.
+        /// </summary>
         public string Value { get; set; }
     }
 }

src/Microsoft.AspNetCore.Authentication.Abstractions/BaseAuthenticationContext.cs

@@ -6,8 +6,17 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Base context for authentication.
+    /// </summary>
     public abstract class BaseAuthenticationContext : BaseContext
     {
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="context">The context.</param>
+        /// <param name="authenticationScheme">The name of the scheme.</param>
+        /// <param name="properties">The properties.</param>
         protected BaseAuthenticationContext(HttpContext context, string authenticationScheme, AuthenticationProperties properties) : base(context)
         {
             if (string.IsNullOrEmpty(authenticationScheme))
@@ -19,6 +28,9 @@ protected BaseAuthenticationContext(HttpContext context, string authenticationSc
             Properties = properties ?? new AuthenticationProperties();
         }
 
+        /// <summary>
+        /// The name of the scheme.
+        /// </summary>
         public string AuthenticationScheme { get; }
 
         /// <summary>

src/Microsoft.AspNetCore.Authentication.Abstractions/BaseContext.cs

@@ -6,8 +6,15 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Base class used by other context classes.
+    /// </summary>
     public abstract class BaseContext
     {
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="context">The request context.</param>
         protected BaseContext(HttpContext context)
         {
             if (context == null)
@@ -18,13 +25,22 @@ protected BaseContext(HttpContext context)
             HttpContext = context;
         }
 
+        /// <summary>
+        /// The context.
+        /// </summary>
         public HttpContext HttpContext { get; }
 
+        /// <summary>
+        /// The request.
+        /// </summary>
         public HttpRequest Request
         {
             get { return HttpContext.Request; }
         }
 
+        /// <summary>
+        /// The response.
+        /// </summary>
         public HttpResponse Response
         {
             get { return HttpContext.Response; }

src/Microsoft.AspNetCore.Authentication.Abstractions/ChallengeBehavior.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Controls how challenge will behave (i.e. 401 vs 403).
+    /// </summary>
     public enum ChallengeBehavior
     {
         Automatic,