From b5300ad0e4c48a9d69b3be27df8bed9db3f959b2 Mon Sep 17 00:00:00 2001
From: Hao Kung <haok@microsoft.com>
Date: Wed, 2 Mar 2016 13:46:47 -0800
Subject: [PATCH] Update doc comments

---
 .../CookieAuthenticationOptions.cs             |  2 +-
 .../OpenIdConnectOptions.cs                    |  2 +-
 .../AuthenticationOptions.cs                   |  2 +-
 .../ClaimsTransformationOptions.cs             |  6 ++++++
 .../IClaimsTransformer.cs                      |  8 ++++++++
 .../RemoteAuthenticationOptions.cs             |  3 +++
 .../AuthorizationOptions.cs                    | 18 ++++++++++++++++++
 .../CookiePolicyOptions.cs                     | 16 ++++++++++++++++
 8 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/src/Microsoft.AspNetCore.Authentication.Cookies/CookieAuthenticationOptions.cs b/src/Microsoft.AspNetCore.Authentication.Cookies/CookieAuthenticationOptions.cs
index dc1a63bbf3..51cf43a0f1 100644
--- a/src/Microsoft.AspNetCore.Authentication.Cookies/CookieAuthenticationOptions.cs
+++ b/src/Microsoft.AspNetCore.Authentication.Cookies/CookieAuthenticationOptions.cs
@@ -13,7 +13,7 @@ using Microsoft.Extensions.Options;
 namespace Microsoft.AspNetCore.Builder
 {
     /// <summary>
-    /// Contains the options used by the CookiesAuthenticationMiddleware
+    /// Configuration options for <see cref="CookieAuthenticationMiddleware"/>.
     /// </summary>
     public class CookieAuthenticationOptions : AuthenticationOptions, IOptions<CookieAuthenticationOptions>
     {
diff --git a/src/Microsoft.AspNetCore.Authentication.OpenIdConnect/OpenIdConnectOptions.cs b/src/Microsoft.AspNetCore.Authentication.OpenIdConnect/OpenIdConnectOptions.cs
index de7bee1633..1b179c3369 100644
--- a/src/Microsoft.AspNetCore.Authentication.OpenIdConnect/OpenIdConnectOptions.cs
+++ b/src/Microsoft.AspNetCore.Authentication.OpenIdConnect/OpenIdConnectOptions.cs
@@ -17,7 +17,7 @@ using Microsoft.IdentityModel.Tokens;
 namespace Microsoft.AspNetCore.Builder
 {
     /// <summary>
-    /// Configuration options for <see cref="OpenIdConnectOptions"/>
+    /// Configuration options for <see cref="OpenIdConnectMiddleware"/>
     /// </summary>
     public class OpenIdConnectOptions : RemoteAuthenticationOptions
     {
diff --git a/src/Microsoft.AspNetCore.Authentication/AuthenticationOptions.cs b/src/Microsoft.AspNetCore.Authentication/AuthenticationOptions.cs
index 8f1fb06912..04d050b06e 100644
--- a/src/Microsoft.AspNetCore.Authentication/AuthenticationOptions.cs
+++ b/src/Microsoft.AspNetCore.Authentication/AuthenticationOptions.cs
@@ -6,7 +6,7 @@ using Microsoft.AspNetCore.Http.Authentication;
 namespace Microsoft.AspNetCore.Builder
 {
     /// <summary>
-    /// Base Options for all authentication middleware
+    /// Base Options for all authentication middleware.
     /// </summary>
     public abstract class AuthenticationOptions
     {
diff --git a/src/Microsoft.AspNetCore.Authentication/ClaimsTransformationOptions.cs b/src/Microsoft.AspNetCore.Authentication/ClaimsTransformationOptions.cs
index 7772457a02..70a76f27c6 100644
--- a/src/Microsoft.AspNetCore.Authentication/ClaimsTransformationOptions.cs
+++ b/src/Microsoft.AspNetCore.Authentication/ClaimsTransformationOptions.cs
@@ -5,8 +5,14 @@ using Microsoft.AspNetCore.Authentication;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Contains the options used by the <see cref="ClaimsTransformationMiddleware"/>.
+    /// </summary>
     public class ClaimsTransformationOptions
     {
+        /// <summary>
+        /// Responsible for transforming the claims principal.
+        /// </summary>
         public IClaimsTransformer Transformer { get; set; }
     }
 }
diff --git a/src/Microsoft.AspNetCore.Authentication/IClaimsTransformer.cs b/src/Microsoft.AspNetCore.Authentication/IClaimsTransformer.cs
index 03eece9318..5111c79714 100644
--- a/src/Microsoft.AspNetCore.Authentication/IClaimsTransformer.cs
+++ b/src/Microsoft.AspNetCore.Authentication/IClaimsTransformer.cs
@@ -6,8 +6,16 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNetCore.Authentication
 {
+    /// <summary>
+    /// Used for claims transformation.
+    /// </summary>
     public interface IClaimsTransformer
     {
+        /// <summary>
+        /// Provides a central transformation point to change the specified principal.
+        /// </summary>
+        /// <param name="principal">The principal to transform.</param>
+        /// <returns>The transformed principal.</returns>
         Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal);
     }
 }
diff --git a/src/Microsoft.AspNetCore.Authentication/RemoteAuthenticationOptions.cs b/src/Microsoft.AspNetCore.Authentication/RemoteAuthenticationOptions.cs
index 0388c04bda..43e011c40e 100644
--- a/src/Microsoft.AspNetCore.Authentication/RemoteAuthenticationOptions.cs
+++ b/src/Microsoft.AspNetCore.Authentication/RemoteAuthenticationOptions.cs
@@ -8,6 +8,9 @@ using Microsoft.AspNetCore.Authentication;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Contains the options used by the <see cref="RemoteAuthenticationHandler"/>.
+    /// </summary>
     public class RemoteAuthenticationOptions : AuthenticationOptions
     {
         /// <summary>
diff --git a/src/Microsoft.AspNetCore.Authorization/AuthorizationOptions.cs b/src/Microsoft.AspNetCore.Authorization/AuthorizationOptions.cs
index c3019c907f..94799af29b 100644
--- a/src/Microsoft.AspNetCore.Authorization/AuthorizationOptions.cs
+++ b/src/Microsoft.AspNetCore.Authorization/AuthorizationOptions.cs
@@ -6,6 +6,9 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNetCore.Authorization
 {
+    /// <summary>
+    /// Provides programmatic configuration used by <see cref="IAuthorizationService"/> and <see cref="IAuthorizationPolicyProvider"/>.
+    /// </summary>
     public class AuthorizationOptions
     {
         private IDictionary<string, AuthorizationPolicy> PolicyMap { get; } = new Dictionary<string, AuthorizationPolicy>(StringComparer.OrdinalIgnoreCase);
@@ -15,6 +18,11 @@ namespace Microsoft.AspNetCore.Authorization
         /// </summary>
         public AuthorizationPolicy DefaultPolicy { get; set; } = new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build();
 
+        /// <summary>
+        /// Add an authorization policy with the provided name.
+        /// </summary>
+        /// <param name="name">The name of the policy.</param>
+        /// <param name="policy">The authorization policy.</param>
         public void AddPolicy(string name, AuthorizationPolicy policy)
         {
             if (name == null)
@@ -30,6 +38,11 @@ namespace Microsoft.AspNetCore.Authorization
             PolicyMap[name] = policy;
         }
 
+        /// <summary>
+        /// Add a policy that is built from a delegate with the provided name.
+        /// </summary>
+        /// <param name="name">The name of the policy.</param>
+        /// <param name="configurePolicy">The delegate that will be used to build the policy.</param>
         public void AddPolicy(string name, Action<AuthorizationPolicyBuilder> configurePolicy)
         {
             if (name == null)
@@ -47,6 +60,11 @@ namespace Microsoft.AspNetCore.Authorization
             PolicyMap[name] = policyBuilder.Build();
         }
 
+        /// <summary>
+        /// Returns the policy for the specified name, or null if a policy with the name does not exist.
+        /// </summary>
+        /// <param name="name">The name of the policy to return.</param>
+        /// <returns>The policy for the specified name, or null if a policy with the name does not exist.</returns>
         public AuthorizationPolicy GetPolicy(string name)
         {
             if (name == null)
diff --git a/src/Microsoft.AspNetCore.CookiePolicy/CookiePolicyOptions.cs b/src/Microsoft.AspNetCore.CookiePolicy/CookiePolicyOptions.cs
index 812c714288..8201b58639 100644
--- a/src/Microsoft.AspNetCore.CookiePolicy/CookiePolicyOptions.cs
+++ b/src/Microsoft.AspNetCore.CookiePolicy/CookiePolicyOptions.cs
@@ -6,12 +6,28 @@ using Microsoft.AspNetCore.CookiePolicy;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Provides programmatic configuration for the <see cref="CookiePolicyMiddleware"/>.
+    /// </summary>
     public class CookiePolicyOptions
     {
+        /// <summary>
+        /// Affects whether cookies must be HttpOnly.
+        /// </summary>
         public HttpOnlyPolicy HttpOnly { get; set; } = HttpOnlyPolicy.None;
+        /// <summary>
+        /// Affects whether cookies must be Secure.
+        /// </summary>
         public SecurePolicy Secure { get; set; } = SecurePolicy.None;
 
+        /// <summary>
+        /// Called when a cookie is appended.
+        /// </summary>
         public Action<AppendCookieContext> OnAppendCookie { get; set; }
+
+        /// <summary>
+        /// Called when a cookie is deleted.
+        /// </summary>
         public Action<DeleteCookieContext> OnDeleteCookie { get; set; }
     }
 }
\ No newline at end of file