Fill XML documentation (part 2)

Owin.Security.Providers/Imgur/ImgurAuthenticationDefaults.cs

@@ -1,87 +1,87 @@
 namespace Owin.Security.Providers.Imgur
 {
-    /// <summary></summary>
+    /// <summary>Configuration strings for the imgur provider.</summary>
     internal static class ImgurAuthenticationDefaults
     {
-        /// <summary></summary>
+        /// <summary>The error message for user authentication failure.</summary>
         internal const string AccessDeniedErrorMessage = "access_denied";
 
-        /// <summary></summary>
+        /// <summary>The name of the access token property in the imgur authentication response.</summary>
         internal const string AccessTokenPropertyName = "access_token";
 
-        /// <summary></summary>
+        /// <summary>The name of the account id property in the imgur authentication response.</summary>
         internal const string AccountIdPropertyName = "account_id";
 
-        /// <summary></summary>
+        /// <summary>The name of the account username property in the imgur authentication response.</summary>
         internal const string AccountUsernamePropertyName = "account_username";
 
-        /// <summary></summary>
+        /// <summary>The name of the provider.</summary>
         internal const string AuthenticationType = "Imgur";
 
-        /// <summary></summary>
+        /// <summary>The grant type to be used.</summary>
         internal const string AuthorizationCodeGrantType = "authorization_code";
 
-        /// <summary></summary>
-        internal const string AuthorizationUri = "https://api.imgur.com/oauth2/authorize";
+        /// <summary>The user authorization endpoint URL.</summary>
+        internal const string AuthorizationUrl = "https://api.imgur.com/oauth2/authorize";
 
-        /// <summary></summary>
+        /// <summary>The default callback path.</summary>
         internal const string CallbackPath = "/signin-imgur";
 
-        /// <summary></summary>
+        /// <summary>The name of the application client id parameter.</summary>
         internal const string ClientIdParameter = "client_id";
 
-        /// <summary></summary>
+        /// <summary>The name of the application client secret parameter.</summary>
         internal const string ClientSecretParameter = "client_secret";
 
-        /// <summary></summary>
+        /// <summary>The name of the response code parameter.</summary>
         internal const string CodeParameter = "code";
 
-        /// <summary></summary>
+        /// <summary>The code type of the authentication response.</summary>
         internal const string CodeResponseType = "code";
 
-        /// <summary></summary>
+        /// <summary>The message for the communication failure error.</summary>
         internal const string CommunicationFailureMessage = "An error occurred while talking with imgur's server.";
 
-        /// <summary></summary>
+        /// <summary>The message for the authentication response deserialization failure error.</summary>
         internal const string DeserializationFailureMessage = "The deserialization of the imgur's response failed. Perhaps imgur changed the response format?";
 
-        /// <summary></summary>
+        /// <summary>The name of the error parameter.</summary>
         internal const string ErrorParameter = "error";
 
-        /// <summary></summary>
+        /// <summary>The name of the access token duration property in the imgur authentication response.</summary>
         internal const string ExpiresInPropertyName = "expires_in";
 
-        /// <summary></summary>
+        /// <summary>The name of the grant type parameter.</summary>
         internal const string GrantTypeParameter = "grant_type";
 
-        /// <summary></summary>
+        /// <summary>The format to use to stringify <see cref="System.Int32"/>s.</summary>
         internal const string Int32Format = "D";
 
-        /// <summary></summary>
+        /// <summary>The message for the invalid authentication ticket error.</summary>
         internal const string InvalidAuthenticationTicketMessage = "Invalid authentication ticket.";
 
-        /// <summary></summary>
+        /// <summary>The name of the refresh token property in the imgur authentication response.</summary>
         internal const string RefreshInPropertyName = "refresh_token";
 
-        /// <summary></summary>
+        /// <summary>The name of the response type parameter.</summary>
         internal const string ResponseTypeParameter = "response_type";
 
-        /// <summary></summary>
+        /// <summary>The name of the scope property in the imgur authentication response.</summary>
         internal const string ScopePropertyName = "scope";
 
-        /// <summary></summary>
+        /// <summary>The name of the state parameter.</summary>
         internal const string StateParameter = "state";
 
-        /// <summary></summary>
+        /// <summary>The name of the token type property in the imgur authentication response.</summary>
         internal const string TokenTypePropertyName = "token_type";
 
-        /// <summary></summary>
-        internal const string TokenUri = "https://api.imgur.com/oauth2/token";
+        /// <summary>The token exchange endpoint URL.</summary>
+        internal const string TokenUrl = "https://api.imgur.com/oauth2/token";
 
-        /// <summary></summary>
+        /// <summary>The version of the provider.</summary>
         internal const string Version = "v1";
 
-        /// <summary></summary>
+        /// <summary>The string value type for <see cref="System.Security.Claims.Claim"/>s.</summary>
         internal const string XmlSchemaString = "http://www.w3.org/2001/XMLSchema#string";
     }
 }

Owin.Security.Providers/Imgur/ImgurAuthenticationHandler.cs

@@ -12,6 +12,7 @@
     using Microsoft.Owin.Logging;
     using Microsoft.Owin.Security;
     using Microsoft.Owin.Security.Infrastructure;
+    using Microsoft.Owin.Security.Provider;
 
     using Newtonsoft.Json;
 
@@ -23,9 +24,9 @@ public class ImgurAuthenticationHandler : AuthenticationHandler<ImgurAuthenticat
         private readonly HttpClient httpClient;
         private readonly ILogger logger;
 
-        /// <summary></summary>
-        /// <param name="httpClient"></param>
-        /// <param name="logger"></param>
+        /// <summary>Creates a new <see cref="ImgurAuthenticationHandler"/>.</summary>
+        /// <param name="httpClient">The <see cref="HttpClient"/> to be used for back channel calls.</param>
+        /// <param name="logger">The <see cref="ILogger"/> to be used by the <see cref="ImgurAuthenticationHandler"/>.</param>
         public ImgurAuthenticationHandler(HttpClient httpClient, ILogger logger)
         {
             if (httpClient == null)
@@ -42,8 +43,8 @@ public ImgurAuthenticationHandler(HttpClient httpClient, ILogger logger)
             this.logger = logger;
         }
 
-        /// <summary></summary>
-        /// <returns></returns>
+        /// <summary>Is called once by common code after initialization.</summary>
+        /// <returns>Return true if the request is handled by this <see cref="AuthenticationMiddleware{TOptions}"/>, returns false if the request should be passed to the next <see cref="AuthenticationMiddleware{TOptions}"/>.</returns>
         public override async Task<bool> InvokeAsync()
         {
             if (!this.Options.CallbackPath.HasValue)
@@ -83,8 +84,8 @@ public override async Task<bool> InvokeAsync()
             return context.IsRequestCompleted;
         }
 
-        /// <summary></summary>
-        /// <returns></returns>
+        /// <summary>Handles authentication challenges by intercepting 401 responses.</summary>
+        /// <returns>A <see cref="Task"/> representing the completed operation.</returns>
         protected override Task ApplyResponseChallengeAsync()
         {
             if (this.Response.StatusCode != 401)
@@ -114,8 +115,9 @@ protected override Task ApplyResponseChallengeAsync()
             return Task.FromResult<object>(null);
         }
 
-        /// <summary></summary>
-        /// <returns></returns>
+        /// <summary>The core authentication logic which must be provided by the <see cref="AuthenticationHandler{TOptions}"/>.</summary>
+        /// <returns>The ticket data provided by the authentication logic.</returns>
+        /// <remarks>Will be invoked at most once per request. Do not call directly, call the wrapping Authenticate method instead.</remarks>
         protected override async Task<AuthenticationTicket> AuthenticateCoreAsync()
         {
             if (this.Request.Query.Get(ImgurAuthenticationDefaults.ErrorParameter) != null)
@@ -152,9 +154,9 @@ protected override async Task<AuthenticationTicket> AuthenticateCoreAsync()
             return new AuthenticationTicket(context.Identity, context.Properties);
         }
 
-        /// <summary></summary>
-        /// <param name="code"></param>
-        /// <returns></returns>
+        /// <summary>Gets the payload for the back channel authentication request.</summary>
+        /// <param name="code">The authorization code supplied by imgur.</param>
+        /// <returns>The <see cref="HttpContent"/> with the payload for the back channel authentication request.</returns>
         private HttpContent GetAuthenticationRequestContent(string code)
         {
             return
@@ -179,12 +181,12 @@ private HttpContent GetAuthenticationRequestContent(string code)
                     });
         }
 
-        /// <summary></summary>
-        /// <param name="code"></param>
-        /// <returns></returns>
+        /// <summary>Gets the <see cref="AuthenticationResponse"/> from imgur.</summary>
+        /// <param name="code">The authorization code supplied by imgur.</param>
+        /// <returns>The <see cref="AuthenticationResponse"/> from imgur.</returns>
         private async Task<AuthenticationResponse> GetAuthenticationResponseAsync(string code)
         {
-            using (var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, ImgurAuthenticationDefaults.TokenUri))
+            using (var httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, ImgurAuthenticationDefaults.TokenUrl))
             {
                 httpRequestMessage.Content = this.GetAuthenticationRequestContent(code);
 
@@ -211,12 +213,12 @@ private async Task<AuthenticationResponse> GetAuthenticationResponseAsync(string
             }
         }
 
-        /// <summary></summary>
-        /// <param name="state"></param>
-        /// <returns></returns>
+        /// <summary>Gets the authorization URL for the back channel call.</summary>
+        /// <param name="state">The encrypted <see cref="AuthenticationProperties"/> for the current authentication session.</param>
+        /// <returns>The authorization URL for the back channel call.</returns>
         private string GetAuthorizationUri(string state)
         {
-            var authorizationUri = ImgurAuthenticationDefaults.AuthorizationUri;
+            var authorizationUri = ImgurAuthenticationDefaults.AuthorizationUrl;
 
             authorizationUri =
                 WebUtilities.AddQueryString(
@@ -239,9 +241,9 @@ private string GetAuthorizationUri(string state)
             return authorizationUri;
         }
 
-        /// <summary></summary>
-        /// <param name="authenticationResponse"></param>
-        /// <returns></returns>
+        /// <summary>Gets the <see cref="ClaimsIdentity"/> for the identity of the user.</summary>
+        /// <param name="authenticationResponse">The <see cref="AuthenticationResponse"/> returned by imgur.</param>
+        /// <returns>The <see cref="ClaimsIdentity"/> for the identity of the user.</returns>
         private ClaimsIdentity GetIdentity(AuthenticationResponse authenticationResponse)
         {
             var identity =
@@ -274,11 +276,11 @@ private ClaimsIdentity GetIdentity(AuthenticationResponse authenticationResponse
             return identity;
         }
 
-        /// <summary></summary>
-        /// <param name="authenticationResponse"></param>
-        /// <param name="identity"></param>
-        /// <param name="properties"></param>
-        /// <returns></returns>
+        /// <summary>Gets the <see cref="ImgurAuthenticatedContext"/> for the current authentication session.</summary>
+        /// <param name="authenticationResponse">The <see cref="AuthenticationResponse"/> returned by imgur.</param>
+        /// <param name="identity">The <see cref="ClaimsIdentity"/> for the identity of the user.</param>
+        /// <param name="properties">The <see cref="AuthenticationProperties"/> for the current authentication session.</param>
+        /// <returns>The <see cref="ImgurAuthenticatedContext"/> for the current authentication session.</returns>
         private ImgurAuthenticatedContext GetImgurAuthenticatedContext(AuthenticationResponse authenticationResponse, ClaimsIdentity identity, AuthenticationProperties properties)
         {
             var context = new ImgurAuthenticatedContext(this.Context, this.Options);
@@ -295,9 +297,9 @@ private ImgurAuthenticatedContext GetImgurAuthenticatedContext(AuthenticationRes
             return context;
         }
 
-        /// <summary></summary>
-        /// <param name="ticket"></param>
-        /// <returns></returns>
+        /// <summary>Gets the <see cref="ImgurReturnEndpointContext"/> for the current authentication session.</summary>
+        /// <param name="ticket">The <see cref="AuthenticationTicket"/> for the current authentication session.</param>
+        /// <returns>The <see cref="ImgurReturnEndpointContext"/> for the current authentication session.</returns>
         private ImgurReturnEndpointContext GetImgurReturnEndpointContext(AuthenticationTicket ticket)
         {
             var context = new ImgurReturnEndpointContext(this.Context, ticket);
@@ -307,9 +309,9 @@ private ImgurReturnEndpointContext GetImgurReturnEndpointContext(AuthenticationT
             return context;
         }
 
-        /// <summary></summary>
-        /// <param name="context"></param>
-        private void SignIn(ImgurReturnEndpointContext context)
+        /// <summary>Adds authentication information to the OWIN context to let the appropriate <see cref="AuthenticationMiddleware{TOptions}"/> authenticate the user.</summary>
+        /// <param name="context">The <see cref="ReturnEndpointContext"/> for the current authentication session.</param>
+        private void SignIn(ReturnEndpointContext context)
         {
             if (context.SignInAsAuthenticationType == null || context.Identity == null)
             {
@@ -331,10 +333,10 @@ private void SignIn(ImgurReturnEndpointContext context)
             this.Context.Authentication.SignIn(context.Properties, identity);
         }
 
-        /// <summary></summary>
-        /// <param name="context"></param>
-        /// <returns></returns>
-        private static string GetRedirectLocation(ImgurReturnEndpointContext context)
+        /// <summary>Gets the URL where the user should be redirect to.</summary>
+        /// <param name="context">The <see cref="ReturnEndpointContext"/> for the current authentication session.</param>
+        /// <returns>The URL where the user should be redirect to.</returns>
+        private static string GetRedirectLocation(ReturnEndpointContext context)
         {
             var location = context.RedirectUri;
 
@@ -346,37 +348,38 @@ private static string GetRedirectLocation(ImgurReturnEndpointContext context)
                         ImgurAuthenticationDefaults.ErrorParameter,
                         ImgurAuthenticationDefaults.AccessDeniedErrorMessage);
             }
+
             return location;
         }
 
-        /// <summary></summary>
+        /// <summary>Response payload returned by imgur with the information of the authenticated user.</summary>
         private class AuthenticationResponse
         {
-            /// <summary></summary>
+            /// <summary>Gets or sets the access token for the authenticated user.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccessTokenPropertyName)]
             public string AccessToken { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the account id of the authenticated user.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccountIdPropertyName)]
             public int AccountId { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the account username of the authenticated user.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.AccountUsernamePropertyName)]
             public string AccountUsername { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the duration of the access token.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.ExpiresInPropertyName)]
             public int ExpiresIn { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the refresh token for the authenticated user.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.RefreshInPropertyName)]
             public string RefreshToken { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the scope of the access token.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.ScopePropertyName)]
             public string Scope { get; set; }
 
-            /// <summary></summary>
+            /// <summary>Gets or sets the type of the access token.</summary>
             [JsonProperty(PropertyName = ImgurAuthenticationDefaults.TokenTypePropertyName)]
             public string TokenType { get; set; }
         }