Add lots of missing doc comments.

Also did some minor renames to match extension method patterns.

src/Microsoft.AspNet.Authentication.Cookies/CookieAppBuilderExtensions.cs

@@ -7,15 +7,15 @@ using Microsoft.AspNet.Authentication.Cookies;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods provided by the cookies authentication middleware
+    /// Extension methods to add cookie authentication capabilities to an HTTP application pipeline.
     /// </summary>
     public static class CookieAppBuilderExtensions
     {
         /// <summary>
-        /// Adds a cookie-based authentication middleware to your web application pipeline.
+        /// Adds the <see cref="CookieAuthenticationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables cookie authentication capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseCookieAuthentication(this IApplicationBuilder app)
         {
             if (app == null)
@@ -27,11 +27,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Adds a cookie-based authentication middleware to your web application pipeline.
+        /// Adds the <see cref="CookieAuthenticationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables cookie authentication capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Used to configure the options for the middleware</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="CookieAuthenticationOptions"/>.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseCookieAuthentication(this IApplicationBuilder app, Action<CookieAuthenticationOptions> configureOptions)
         {
             if (app == null)
@@ -48,11 +48,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Adds a cookie-based authentication middleware to your web application pipeline.
+        /// Adds the <see cref="CookieAuthenticationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables cookie authentication capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">Used to configure the middleware</param>
+        /// <param name="options">A <see cref="JwtBearerOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseCookieAuthentication(this IApplicationBuilder app, CookieAuthenticationOptions options)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.Cookies/CookieServiceCollectionExtensions.cs

@@ -8,10 +8,16 @@ using Microsoft.Extensions.Configuration;
 namespace Microsoft.Extensions.DependencyInjection
 {
     /// <summary>
-    /// Extension methods provided by the cookies authentication middleware
+    /// Extension methods for setting up cookie authentication services in an <see cref="IServiceCollection" />.
     /// </summary>
     public static class CookieServiceCollectionExtensions
     {
+        /// <summary>
+        /// Adds cookie authentication services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <param name="configure">An action delegate to configure the provided <see cref="CookieAuthenticationOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddCookieAuthentication(this IServiceCollection services, Action<CookieAuthenticationOptions> configure)
         {
             if (services == null)
@@ -27,6 +33,12 @@ namespace Microsoft.Extensions.DependencyInjection
             return services.Configure(configure);
         }
 
+        /// <summary>
+        /// Adds cookie authentication services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <param name="config">An <see cref="IConfiguration"/> instance that contains configuration data representing  a <see cref="CookieAuthenticationOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddCookieAuthentication(this IServiceCollection services, IConfiguration config)
         {
             if (services == null)
@@ -42,4 +54,4 @@ namespace Microsoft.Extensions.DependencyInjection
             return services.Configure<CookieAuthenticationOptions>(config);
         }
     }
-}
+}

src/Microsoft.AspNet.Authentication.Facebook/FacebookAppBuilderExtensions.cs

@@ -7,15 +7,16 @@ using Microsoft.AspNet.Authentication.Facebook;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="FacebookMiddleware"/>.
+    /// Extension methods to add Facebook authentication capabilities to an HTTP application pipeline.
     /// </summary>
     public static class FacebookAppBuilderExtensions
     {
         /// <summary>
-        /// Authenticate users using Facebook.
+        /// Adds the <see cref="FacebookMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Facebook authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
+        /// <param name="options">A <see cref="FacebookOptions"/> that specifies options for the middleware.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseFacebookAuthentication(this IApplicationBuilder app, FacebookOptions options)
         {
             if (app == null)
@@ -32,11 +33,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Authenticate users using Facebook.
+        /// Adds the <see cref="FacebookMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Facebook authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Configures the options.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="FacebookOptions"/>.</param>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseFacebookAuthentication(this IApplicationBuilder app, Action<FacebookOptions> configureOptions)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.Google/GoogleAppBuilderExtensions.cs

@@ -7,16 +7,16 @@ using Microsoft.AspNet.Authentication.Google;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="GoogleMiddleware"/>.
+    /// Extension methods to add Google authentication capabilities to an HTTP application pipeline.
     /// </summary>
     public static class GoogleAppBuilderExtensions
     {
         /// <summary>
-        /// Authenticate users using Google OAuth 2.0.
+        /// Adds the <see cref="GoogleMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Google authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">The Middleware options.</param>
+        /// <param name="options">A <see cref="GoogleOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseGoogleAuthentication(this IApplicationBuilder app, GoogleOptions options)
         {
             if (app == null)
@@ -33,12 +33,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Authenticate users using Google OAuth 2.0.
+        /// Adds the <see cref="GoogleMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Google authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Used to configure Middleware options.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="GoogleOptions"/>.</param>
-        /// <param name="optionsName">Name of the options instance to be used</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
         public static IApplicationBuilder UseGoogleAuthentication(this IApplicationBuilder app, Action<GoogleOptions> configureOptions)
         {
             if (app == null)
@@ -54,4 +53,4 @@ namespace Microsoft.AspNet.Builder
             return app.UseGoogleAuthentication(options);
         }
     }
-}
+}

src/Microsoft.AspNet.Authentication.JwtBearer/JwtBearerAppBuilderExtensions.cs

@@ -7,21 +7,22 @@ using Microsoft.AspNet.Authentication.JwtBearer;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods to add OpenIdConnect Bearer authentication capabilities to an HTTP application pipeline
+    /// Extension methods to add OpenIdConnect Bearer authentication capabilities to an HTTP application pipeline.
     /// </summary>
     public static class JwtBearerAppBuilderExtensions
     {
         /// <summary>
-        /// Adds Bearer token processing to an HTTP application pipeline. This middleware understands appropriately
+        /// Adds the <see cref="JwtBearerMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Bearer token processing capabilities.
+        /// This middleware understands appropriately
         /// formatted and secured tokens which appear in the request header. If the Options.AuthenticationMode is Active, the
         /// claims within the bearer token are added to the current request's IPrincipal User. If the Options.AuthenticationMode 
         /// is Passive, then the current request is not modified, but IAuthenticationManager AuthenticateAsync may be used at
         /// any time to obtain the claims from the request's bearer token.
         /// See also http://tools.ietf.org/html/rfc6749
         /// </summary>
-        /// <param name="app">The application builder</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">Options which control the processing of the bearer header.</param>
+        /// <param name="options">A <see cref="JwtBearerOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The application builder</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseJwtBearerAuthentication(this IApplicationBuilder app, JwtBearerOptions options)
         {
             if (app == null)
@@ -38,16 +39,17 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Adds Bearer token processing to an HTTP application pipeline. This middleware understands appropriately
+        /// Adds the <see cref="JwtBearerMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Bearer token processing capabilities.
+        /// This middleware understands appropriately
         /// formatted and secured tokens which appear in the request header. If the Options.AuthenticationMode is Active, the
         /// claims within the bearer token are added to the current request's IPrincipal User. If the Options.AuthenticationMode 
         /// is Passive, then the current request is not modified, but IAuthenticationManager AuthenticateAsync may be used at
         /// any time to obtain the claims from the request's bearer token.
         /// See also http://tools.ietf.org/html/rfc6749
         /// </summary>
-        /// <param name="app">The application builder</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Used to configure Middleware options.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="JwtBearerOptions"/>.</param>
-        /// <returns>The application builder</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseJwtBearerAuthentication(this IApplicationBuilder app, Action<JwtBearerOptions> configureOptions)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.MicrosoftAccount/MicrosoftAccountAppBuilderExtensions.cs

@@ -7,10 +7,16 @@ using Microsoft.AspNet.Authentication.MicrosoftAccount;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="MicrosoftAccountMiddleware"/>
+    /// Extension methods to add Microsoft Account authentication capabilities to an HTTP application pipeline.
     /// </summary>
-    public static class MicrosoftAccountAuthenticationExtensions
+    public static class MicrosoftAccountAppBuilderExtensions
     {
+        /// <summary>
+        /// Adds the <see cref="MicrosoftAccountMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Microsoft Account authentication capabilities.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="options">A <see cref="MicrosoftAccountOptions"/> that specifies options for the middleware.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseMicrosoftAccountAuthentication(this IApplicationBuilder app, MicrosoftAccountOptions options)
         {
             if (app == null)
@@ -26,6 +32,12 @@ namespace Microsoft.AspNet.Builder
             return app.UseMiddleware<MicrosoftAccountMiddleware>(options);
         }
 
+        /// <summary>
+        /// Adds the <see cref="MicrosoftAccountMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Microsoft Account authentication capabilities.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="MicrosoftAccountOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseMicrosoftAccountAuthentication(this IApplicationBuilder app, Action<MicrosoftAccountOptions> configureOptions)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.OAuth/OAuthAppBuilderExtensions.cs

@@ -7,16 +7,16 @@ using Microsoft.AspNet.Authentication.OAuth;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="OAuthMiddleware"/>
+    /// Extension methods to add OAuth 2.0 authentication capabilities to an HTTP application pipeline.
     /// </summary>
-    public static class OAuthExtensions
+    public static class OAuthAppBuilderExtensions
     {
         /// <summary>
-        /// Authenticate users using OAuth.
+        /// Adds the <see cref="OAuthMiddleware{TOptions}"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables OAuth 2.0 authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Configures the middleware options.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="OAuthOptions"/>.</param>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseOAuthAuthentication(this IApplicationBuilder app, Action<OAuthOptions> configureOptions)
         {
             if (app == null)
@@ -38,11 +38,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Authenticate users using OAuth.
+        /// Adds the <see cref="OAuthMiddleware{TOptions}"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables OAuth 2.0 authentication capabilities.
         /// </summary>
-        /// <param name="app">The <see cref="IApplicationBuilder"/> passed to the configure method.</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">The middleware configuration options.</param>
+        /// <param name="options">A <see cref="OAuthOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The updated <see cref="IApplicationBuilder"/>.</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseOAuthAuthentication(this IApplicationBuilder app, OAuthOptions options)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.OpenIdConnect/OpenIdConnectAppBuilderExtensions.cs

@@ -7,16 +7,16 @@ using Microsoft.AspNet.Authentication.OpenIdConnect;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="OpenIdConnectMiddleware"/>
+    /// Extension methods to add OpenID Connect authentication capabilities to an HTTP application pipeline.
     /// </summary>
-    public static class OpenIdConnectExtensions
+    public static class OpenIdConnectAppBuilderExtensions
     {
         /// <summary>
-        /// Adds the <see cref="OpenIdConnectMiddleware"/> into the ASP.NET runtime.
+        /// Adds the <see cref="OpenIdConnectMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables OpenID Connect authentication capabilities.
         /// </summary>
-        /// <param name="app">The application builder</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">Options which control the processing of the OpenIdConnect protocol and token validation.</param>
+        /// <param name="options">An action delegate to configure the provided <see cref="OpenIdConnectOptions"/>.</param>
-        /// <returns>The application builder</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseOpenIdConnectAuthentication(this IApplicationBuilder app, Action<OpenIdConnectOptions> configureOptions)
         {
             if (app == null)
@@ -34,11 +34,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Adds the <see cref="OpenIdConnectMiddleware"/> into the ASP.NET runtime.
+        /// Adds the <see cref="OpenIdConnectMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables OpenID Connect authentication capabilities.
         /// </summary>
-        /// <param name="app">The application builder</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">Options which control the processing of the OpenIdConnect protocol and token validation.</param>
+        /// <param name="options">An <see cref="OpenIdConnectOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The application builder</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseOpenIdConnectAuthentication(this IApplicationBuilder app, OpenIdConnectOptions options)
         {
             if (app == null)

src/Microsoft.AspNet.Authentication.Twitter/TwitterAppBuilderExtensions.cs

@@ -7,10 +7,16 @@ using Microsoft.AspNet.Authentication.Twitter;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods for using <see cref="TwitterMiddleware"/>
+    /// Extension methods to add Twitter authentication capabilities to an HTTP application pipeline.
     /// </summary>
     public static class TwitterAppBuilderExtensions
     {
+        /// <summary>
+        /// Adds the <see cref="TwitterMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Twitter authentication capabilities.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="TwitterOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseTwitterAuthentication(this IApplicationBuilder app, Action<TwitterOptions> configureOptions = null)
         {
             if (app == null)
@@ -26,6 +32,12 @@ namespace Microsoft.AspNet.Builder
             return app.UseTwitterAuthentication(options);
         }
 
+        /// <summary>
+        /// Adds the <see cref="TwitterMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables Twitter authentication capabilities.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="options">A <see cref="TwitterOptions"/> that specifies options for the middleware.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseTwitterAuthentication(this IApplicationBuilder app, TwitterOptions options)
         {
             if (app == null)
@@ -40,6 +52,5 @@ namespace Microsoft.AspNet.Builder
 
             return app.UseMiddleware<TwitterMiddleware>(options);
         }
-
     }
 }

src/Microsoft.AspNet.Authentication/AuthenticationServiceCollectionExtensions.cs

@@ -6,8 +6,16 @@ using Microsoft.AspNet.Authentication;
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods for setting up authentication services in an <see cref="IServiceCollection" />.
+    /// </summary>
     public static class AuthenticationServiceCollectionExtensions
     {
+        /// <summary>
+        /// Adds authentication services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddAuthentication(this IServiceCollection services)
         {
             if (services == null)
@@ -20,6 +28,12 @@ namespace Microsoft.Extensions.DependencyInjection
             return services;
         }
 
+        /// <summary>
+        /// Adds authentication services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="SharedAuthenticationOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddAuthentication(this IServiceCollection services, Action<SharedAuthenticationOptions> configureOptions)
         {
             if (services == null)

src/Microsoft.AspNet.Authentication/ClaimsTransformationAppBuilderExtensions.cs

@@ -9,27 +9,27 @@ using Microsoft.AspNet.Authentication;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods provided by the claims transformation authentication middleware
+    /// Extension methods to add claims transformation capabilities to an HTTP application pipeline.
     /// </summary>
     public static class ClaimsTransformationAppBuilderExtensions
     {
         /// <summary>
-        /// Adds a claims transformation middleware to your web application pipeline.
+        /// Adds the <see cref="ClaimsTransformationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables claims transformation capabilities.
         /// </summary>
-        /// <param name="options">The options for the middleware</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="options">A <see cref="ClaimsTransformationOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseClaimsTransformation(this IApplicationBuilder app, ClaimsTransformationOptions options)
         {
             return app.UseMiddleware<ClaimsTransformationMiddleware>(options);
         }
 
         /// <summary>
-        /// Adds a claims transformation middleware to your web application pipeline.
+        /// Adds the <see cref="ClaimsTransformationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables claims transformation capabilities.
         /// </summary>
-        /// <param name="options">The options for the middleware</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="transform">A function that asynchronously transforms one <see cref="ClaimsPrincipal"/> to another.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseClaimsTransformation(this IApplicationBuilder app, Func<ClaimsPrincipal, Task<ClaimsPrincipal>> transform)
         {
             var options = new ClaimsTransformationOptions();
@@ -41,11 +41,11 @@ namespace Microsoft.AspNet.Builder
         }
 
         /// <summary>
-        /// Adds a claims transformation middleware to your web application pipeline.
+        /// Adds the <see cref="ClaimsTransformationMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables claims transformation capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Used to configure the options for the middleware</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="ClaimsTransformationOptions"/>.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseClaimsTransformation(this IApplicationBuilder app, Action<ClaimsTransformationOptions> configureOptions)
         {
             var options = new ClaimsTransformationOptions();
@@ -56,4 +56,4 @@ namespace Microsoft.AspNet.Builder
             return app.UseClaimsTransformation(options);
         }
     }
-}
+}

src/Microsoft.AspNet.Authorization/AllowAnonymousAttribute.cs

@@ -5,6 +5,9 @@ using System;
 
 namespace Microsoft.AspNet.Authorization
 {
+    /// <summary>
+    /// Specifies that the class or method that this attribute is applied to does not require authorization.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
     public class AllowAnonymousAttribute : Attribute, IAllowAnonymous
     {

src/Microsoft.AspNet.Authorization/AuthorizationServiceCollectionExtensions.cs

@@ -7,8 +7,16 @@ using Microsoft.Extensions.DependencyInjection.Extensions;
 
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    /// Extension methods for setting up authorization services in an <see cref="IServiceCollection" />.
+    /// </summary>
     public static class AuthorizationServiceCollectionExtensions
     {
+        /// <summary>
+        /// Adds authorization services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddAuthorization(this IServiceCollection services)
         {
             if (services == null)
@@ -22,6 +30,12 @@ namespace Microsoft.Extensions.DependencyInjection
             return services;
         }
 
+        /// <summary>
+        /// Adds authorization services to the specified <see cref="IServiceCollection" />. 
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
+        /// <param name="configure">An action delegate to configure the provided <see cref="AuthorizationOptions"/>.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IServiceCollection AddAuthorization(this IServiceCollection services, Action<AuthorizationOptions> configure)
         {
             if (services == null)
@@ -38,4 +52,4 @@ namespace Microsoft.Extensions.DependencyInjection
             return services.AddAuthorization();
         }
     }
-}
+}

src/Microsoft.AspNet.Authorization/AuthorizeAttribute.cs

@@ -5,21 +5,34 @@ using System;
 
 namespace Microsoft.AspNet.Authorization
 {
+    /// <summary>
+    /// Specifies that the class or method that this attribute is applied to requires the specified authorization.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
     public class AuthorizeAttribute : Attribute, IAuthorizeData
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthorizeAttribute"/> class. 
+        /// </summary>
         public AuthorizeAttribute() { }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AuthorizeAttribute"/> class with the specified policy. 
+        /// </summary>
+        /// <param name="policy">The name of the policy to require for authorization.</param>
         public AuthorizeAttribute(string policy)
         {
             Policy = policy;
         }
 
+        /// <inheritdoc />
         public string Policy { get; set; }
 
+        /// <inheritdoc />
         // REVIEW: can we get rid of the , deliminated in Roles/AuthTypes
         public string Roles { get; set; }
 
+        /// <inheritdoc />
         public string ActiveAuthenticationSchemes { get; set; }
     }
 }

src/Microsoft.AspNet.Authorization/IAuthorizeData.cs

@@ -3,10 +3,19 @@
 
 namespace Microsoft.AspNet.Authorization
 {
+    /// <summary>
+    /// Defines the set of data required to apply authorization rules to a resource.
+    /// </summary>
     public interface IAuthorizeData
     {
+        /// <summary>
+        /// Gets or sets the policy name that determines access to the resource.
+        /// </summary>
         string Policy { get; set; }
 
+        /// <summary>
+        /// Gets or sets a comma-separated list of roles that are allowed to access the resource.
+        /// </summary>
         string Roles { get; set; }
 
         string ActiveAuthenticationSchemes { get; set; }

src/Microsoft.AspNet.CookiePolicy/CookiePolicyAppBuilderExtensions.cs

@@ -7,27 +7,27 @@ using Microsoft.AspNet.CookiePolicy;
 namespace Microsoft.AspNet.Builder
 {
     /// <summary>
-    /// Extension methods provided by the cookie policy middleware
+    /// Extension methods to add cookie policy capabilities to an HTTP application pipeline.
     /// </summary>
     public static class CookiePolicyAppBuilderExtensions
     {
         /// <summary>
-        /// Adds a cookie policy middleware to your web application pipeline.
+        /// Adds the <see cref="CookiePolicyMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables cookie policy capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="options">The options for the middleware</param>
+        /// <param name="options">A <see cref="CookiePolicyOptions"/> that specifies options for the middleware.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseCookiePolicy(this IApplicationBuilder app, CookiePolicyOptions options)
         {
             return app.UseMiddleware<CookiePolicyMiddleware>(options);
         }
 
         /// <summary>
-        /// Adds a cookie policy middleware to your web application pipeline.
+        /// Adds the <see cref="CookiePolicyMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/>, which enables cookie policy capabilities.
         /// </summary>
-        /// <param name="app">The IApplicationBuilder passed to your configuration method</param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
-        /// <param name="configureOptions">Used to configure the options for the middleware</param>
+        /// <param name="configureOptions">An action delegate to configure the provided <see cref="CookiePolicyOptions"/>.</param>
-        /// <returns>The original app parameter</returns>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseCookiePolicy(this IApplicationBuilder app, Action<CookiePolicyOptions> configureOptions)
         {
             var options = new CookiePolicyOptions();