Add doc-comments for main APIs

- Coherence-Signed#75

src/Microsoft.AspNet.Http.Abstractions/Extensions/HttpResponseWritingExtensions.cs

@@ -16,10 +16,10 @@ namespace Microsoft.AspNet.Http
         /// <summary>
         /// Writes the given text to the response body. UTF-8 encoding will be used.
         /// </summary>
-        /// <param name="response"></param>
-        /// <param name="text"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="response">The <see cref="HttpResponse"/>.</param>
+        /// <param name="text">The text to write to the response.</param>
+        /// <param name="cancellationToken">Notifies when request operations should be cancelled.</param>
+        /// <returns>A task that represents the completion of the write operation.</returns>
         public static Task WriteAsync(this HttpResponse response, string text, CancellationToken cancellationToken = default(CancellationToken))
         {
             if (response == null)
@@ -38,11 +38,11 @@ namespace Microsoft.AspNet.Http
         /// <summary>
         /// Writes the given text to the response body using the given encoding.
         /// </summary>
-        /// <param name="response"></param>
-        /// <param name="text"></param>
-        /// <param name="encoding"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="response">The <see cref="HttpResponse"/>.</param>
+        /// <param name="text">The text to write to the response.</param>
+        /// <param name="encoding">The encoding to use.</param>
+        /// <param name="cancellationToken">Notifies when request operations should be cancelled.</param>
+        /// <returns>A task that represents the completion of the write operation.</returns>
         public static Task WriteAsync(this HttpResponse response, string text, Encoding encoding, CancellationToken cancellationToken = default(CancellationToken))
         {
             if (response == null)

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapExtensions.cs

@@ -7,16 +7,19 @@ using Microsoft.AspNet.Builder.Extensions;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Extension methods for the <see cref="MapMiddleware"/>.
+    /// </summary>
     public static class MapExtensions
     {
         /// <summary>
-        /// If the request path starts with the given pathMatch, execute the app configured via configuration parameter instead of
-        /// continuing to the next component in the pipeline.
+        /// Branches the request pipeline based on matches of the given request path. If the request path starts with
+        /// the given path, the branch is executed.
         /// </summary>
-        /// <param name="app"></param>
-        /// <param name="pathMatch">The path to match</param>
-        /// <param name="configuration">The branch to take for positive path matches</param>
-        /// <returns></returns>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
+        /// <param name="pathMatch">The request path to match.</param>
+        /// <param name="configuration">The branch to take for positive path matches.</param>
+        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
         public static IApplicationBuilder Map(this IApplicationBuilder app, PathString pathMatch, Action<IApplicationBuilder> configuration)
         {
             if (app == null)
@@ -39,7 +42,7 @@ namespace Microsoft.AspNet.Builder
             configuration(branchBuilder);
             var branch = branchBuilder.Build();
 
-            var options = new MapOptions()
+            var options = new MapOptions
             {
                 Branch = branch,
                 PathMatch = pathMatch,

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapMiddleware.cs

@@ -7,11 +7,19 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Builder.Extensions
 {
+    /// <summary>
+    /// Respresents a middleware that maps a request path to a sub-request pipeline.
+    /// </summary>
     public class MapMiddleware
     {
         private readonly RequestDelegate _next;
         private readonly MapOptions _options;
 
+        /// <summary>
+        /// Creates a new instace of <see cref="MapMiddleware"/>.
+        /// </summary>
+        /// <param name="next">The delegate representing the next middleware in the request pipeline.</param>
+        /// <param name="options">The middleware options.</param>
         public MapMiddleware(RequestDelegate next, MapOptions options)
         {
             if (next == null)
@@ -28,6 +36,11 @@ namespace Microsoft.AspNet.Builder.Extensions
             _options = options;
         }
 
+        /// <summary>
+        /// Executes the middleware.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+        /// <returns>A task that represents the execution of this middleware.</returns>
         public async Task Invoke(HttpContext context)
         {
             if (context == null)

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapOptions.cs

@@ -6,17 +6,17 @@ using Microsoft.AspNet.Http;
 namespace Microsoft.AspNet.Builder.Extensions
 {
     /// <summary>
-    /// Options for the Map middleware
+    /// Options for the <see cref="MapMiddleware"/>.
     /// </summary>
     public class MapOptions
     {
         /// <summary>
-        /// The path to match
+        /// The path to match.
         /// </summary>
         public PathString PathMatch { get; set; }
 
         /// <summary>
-        /// The branch taken for a positive match
+        /// The branch taken for a positive match.
         /// </summary>
         public RequestDelegate Branch { get; set; }
     }

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenExtensions.cs

@@ -11,7 +11,7 @@ namespace Microsoft.AspNet.Builder
     using Predicate = Func<HttpContext, bool>;
 
     /// <summary>
-    /// Extension methods for the MapWhenMiddleware
+    /// Extension methods for the <see cref="MapWhenMiddleware"/>.
     /// </summary>
     public static class MapWhenExtensions
     {

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenMiddleware.cs

@@ -7,11 +7,19 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Builder.Extensions
 {
+    /// <summary>
+    /// Respresents a middleware that runs a sub-request pipeline when a given predicate is matched.
+    /// </summary>
     public class MapWhenMiddleware
     {
         private readonly RequestDelegate _next;
         private readonly MapWhenOptions _options;
 
+        /// <summary>
+        /// Creates a new instance of <see cref="MapWhenMiddleware"/>.
+        /// </summary>
+        /// <param name="next">The delegate representing the next middleware in the request pipeline.</param>
+        /// <param name="options">The middleware options.</param>
         public MapWhenMiddleware(RequestDelegate next, MapWhenOptions options)
         {
             if (next == null)
@@ -28,6 +36,11 @@ namespace Microsoft.AspNet.Builder.Extensions
             _options = options;
         }
 
+        /// <summary>
+        /// Executes the middleware.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+        /// <returns>A task that represents the execution of this middleware.</returns>
         public async Task Invoke(HttpContext context)
         {
             if (context == null)

src/Microsoft.AspNet.Http.Abstractions/Extensions/MapWhenOptions.cs

@@ -7,14 +7,14 @@ using Microsoft.AspNet.Http;
 namespace Microsoft.AspNet.Builder.Extensions
 {
     /// <summary>
-    /// Options for the MapWhen middleware
+    /// Options for the <see cref="MapWhenMiddleware"/>.
     /// </summary>
     public class MapWhenOptions
     {
         private Func<HttpContext, bool> _predicate;
 
         /// <summary>
-        /// The user callback that determines if the branch should be taken
+        /// The user callback that determines if the branch should be taken.
         /// </summary>
         public Func<HttpContext, bool> Predicate
         {
@@ -34,7 +34,7 @@ namespace Microsoft.AspNet.Builder.Extensions
         }
 
         /// <summary>
-        /// The branch taken for a positive match
+        /// The branch taken for a positive match.
         /// </summary>
         public RequestDelegate Branch { get; set; }
     }

src/Microsoft.AspNet.Http.Abstractions/Extensions/RunExtensions.cs

@@ -5,8 +5,16 @@ using System;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Extension methods for adding terminal middleware.
+    /// </summary>
     public static class RunExtensions
     {
+        /// <summary>
+        /// Adds a terminal middleware delagate to the application's request pipeline.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
+        /// <param name="handler">A delegate that handles the request.</param>
         public static void Run(this IApplicationBuilder app, RequestDelegate handler)
         {
             if (app == null)

src/Microsoft.AspNet.Http.Abstractions/Extensions/UseExtensions.cs

@@ -7,14 +7,17 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Extension methods for adding middleware.
+    /// </summary>
     public static class UseExtensions
     {
         /// <summary>
-        /// Use middleware defined in-line.
+        /// Adds a middleware delagate defined in-line to the application's request pipeline.
         /// </summary>
-        /// <param name="app"></param>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
         /// <param name="middleware">A function that handles the request or calls the given next function.</param>
-        /// <returns></returns>
+        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
         public static IApplicationBuilder Use(this IApplicationBuilder app, Func<HttpContext, Func<Task>, Task> middleware)
         {
             return app.Use(next =>

src/Microsoft.AspNet.Http.Abstractions/Extensions/UseMiddlewareExtensions.cs

@@ -11,18 +11,36 @@ using Microsoft.Extensions.Internal;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Extension methods for adding typed middlware.
+    /// </summary>
     public static class UseMiddlewareExtensions
     {
         const string InvokeMethodName = "Invoke";
-        public static IApplicationBuilder UseMiddleware<T>(this IApplicationBuilder builder, params object[] args)
+
+        /// <summary>
+        /// Adds a middleware type to the application's request pipeline.
+        /// </summary>
+        /// <typeparam name="TMiddleware">The middleware type.</typeparam>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
+        /// <param name="args">The arguments to pass to the middleware type instance's constructor.</param>
+        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        public static IApplicationBuilder UseMiddleware<TMiddleware>(this IApplicationBuilder app, params object[] args)
         {
-            return builder.UseMiddleware(typeof(T), args);
+            return app.UseMiddleware(typeof(TMiddleware), args);
         }
 
-        public static IApplicationBuilder UseMiddleware(this IApplicationBuilder builder, Type middleware, params object[] args)
+        /// <summary>
+        /// Adds a middleware type to the application's request pipeline.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> instance.</param>
+        /// <param name="middleware">The middleware type.</param>
+        /// <param name="args">The arguments to pass to the middleware type instance's constructor.</param>
+        /// <returns>The <see cref="IApplicationBuilder"/> instance.</returns>
+        public static IApplicationBuilder UseMiddleware(this IApplicationBuilder app, Type middleware, params object[] args)
         {
-            var applicationServices = builder.ApplicationServices;
-            return builder.Use(next =>
+            var applicationServices = app.ApplicationServices;
+            return app.Use(next =>
             {
                 var methods = middleware.GetMethods(BindingFlags.Instance | BindingFlags.Public);
                 var invokeMethods = methods.Where(m => string.Equals(m.Name, InvokeMethodName, StringComparison.Ordinal)).ToArray();
@@ -48,7 +66,7 @@ namespace Microsoft.AspNet.Builder
                     throw new InvalidOperationException(Resources.FormatException_UseMiddlewareNoParameters(InvokeMethodName,nameof(HttpContext)));
                 }
 
-                var instance = ActivatorUtilities.CreateInstance(builder.ApplicationServices, middleware, new[] { next }.Concat(args).ToArray());
+                var instance = ActivatorUtilities.CreateInstance(app.ApplicationServices, middleware, new[] { next }.Concat(args).ToArray());
                 if (parameters.Length == 1)
                 {
                     return (RequestDelegate)methodinfo.CreateDelegate(typeof(RequestDelegate), instance);

src/Microsoft.AspNet.Http.Abstractions/HttpContext.cs

@@ -10,34 +10,80 @@ using Microsoft.AspNet.Http.Features;
 
 namespace Microsoft.AspNet.Http
 {
+    /// <summary>
+    /// Encapsulates all HTTP-specific information about an individual HTTP request.
+    /// </summary>
     public abstract class HttpContext
     {
+        /// <summary>
+        /// Gets the collection of HTTP features provided by the server and middleware available on this request.
+        /// </summary>
         public abstract IFeatureCollection Features { get; }
 
+        /// <summary>
+        /// Gets the <see cref="HttpRequest"/> object for this request.
+        /// </summary>
         public abstract HttpRequest Request { get; }
 
+        /// <summary>
+        /// Gets the <see cref="HttpResponse"/> object for this request.
+        /// </summary>
         public abstract HttpResponse Response { get; }
 
+        /// <summary>
+        /// Gets information about the underlying connection for this request.
+        /// </summary>
         public abstract ConnectionInfo Connection { get; }
 
+        /// <summary>
+        /// Gets an object that manages the establishment of WebSocket connections for this request.
+        /// </summary>
         public abstract WebSocketManager WebSockets { get; }
 
+        /// <summary>
+        /// Gets an object that facilitates authentication for this request.
+        /// </summary>
         public abstract AuthenticationManager Authentication { get; }
 
+        /// <summary>
+        /// Gets or sets the the user for this request.
+        /// </summary>
         public abstract ClaimsPrincipal User { get; set; }
 
+        /// <summary>
+        /// Gets or sets a key/value collection that can be used to share data within the scope of this request.
+        /// </summary>
         public abstract IDictionary<object, object> Items { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IServiceProvider"/> that provides access to the application's service container.
+        /// </summary>
         public abstract IServiceProvider ApplicationServices { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="IServiceProvider"/> that provides access to the request's service container.
+        /// </summary>
         public abstract IServiceProvider RequestServices { get; set; }
 
+        /// <summary>
+        /// Notifies when the connection underlying this request is aborted and thus request operations should be
+        /// cancelled.
+        /// </summary>
         public abstract CancellationToken RequestAborted { get; set; }
 
+        /// <summary>
+        /// Gets or sets a unique identifier to represent this request in trace logs.
+        /// </summary>
         public abstract string TraceIdentifier { get; set; }
 
+        /// <summary>
+        /// Gets or sets the object used to manage user session data for this request.
+        /// </summary>
         public abstract ISession Session { get; set; }
 
+        /// <summary>
+        /// Aborts the connection underlying this request.
+        /// </summary>
         public abstract void Abort();
     }
 }

src/Microsoft.AspNet.Http.Abstractions/HttpRequest.cs

@@ -7,8 +7,14 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Http
 {
+    /// <summary>
+    /// Represents the incoming side of an individual HTTP request.
+    /// </summary>
     public abstract class HttpRequest
     {
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/> this request;
+        /// </summary>
         public abstract HttpContext HttpContext { get; }
 
         /// <summary>

src/Microsoft.AspNet.Http.Abstractions/HttpResponse.cs

@@ -7,6 +7,9 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Http
 {
+    /// <summary>
+    /// Represents the outgoing side of an individual HTTP request.
+    /// </summary>
     public abstract class HttpResponse
     {
         private static readonly Func<object, Task> _callbackDelegate = callback => ((Func<Task>)callback)();
@@ -16,34 +19,89 @@ namespace Microsoft.AspNet.Http
             return Task.FromResult(0);
         };
 
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/> for this request.
+        /// </summary>
         public abstract HttpContext HttpContext { get; }
 
+        /// <summary>
+        /// Gets or sets the HTTP response code.
+        /// </summary>
         public abstract int StatusCode { get; set; }
 
+        /// <summary>
+        /// Gets the response headers.
+        /// </summary>
         public abstract IHeaderDictionary Headers { get; }
 
+        /// <summary>
+        /// Gets the response body <see cref="Stream"/>.
+        /// </summary>
         public abstract Stream Body { get; set; }
 
+        /// <summary>
+        /// Gets or sets the value for the <c>Content-Length</c> response header.
+        /// </summary>
         public abstract long? ContentLength { get; set; }
 
+        /// <summary>
+        /// Gets or sets the value for the <c>Content-Type</c> response header.
+        /// </summary>
         public abstract string ContentType { get; set; }
 
+        /// <summary>
+        /// Gets an object that can be used to manage cookies for this response.
+        /// </summary>
         public abstract IResponseCookies Cookies { get; }
 
+        /// <summary>
+        /// Gets a value indicating whether response headers have been sent to the client.
+        /// </summary>
         public abstract bool HasStarted { get; }
 
+        /// <summary>
+        /// Adds a delegate to be invoked just before response headers will be sent to the client.
+        /// </summary>
+        /// <param name="callback">The delegate to execute.</param>
+        /// <param name="state">A state object to capture and pass back to the delegate.</param>
         public abstract void OnStarting(Func<object, Task> callback, object state);
 
+        /// <summary>
+        /// Adds a delegate to be invoked just before response headers will be sent to the client.
+        /// </summary>
+        /// <param name="callback">The delegate to execute.</param>
         public virtual void OnStarting(Func<Task> callback) => OnStarting(_callbackDelegate, callback);
 
+        /// <summary>
+        /// Adds a delegate to be invoked after the response has finished being sent to the client.
+        /// </summary>
+        /// <param name="callback">The delegate to invoke.</param>
+        /// <param name="state">A state object to capture and pass back to the delegate.</param>
         public abstract void OnCompleted(Func<object, Task> callback, object state);
 
+        /// <summary>
+        /// Registers an object for disposal by the host once the request has finished processing.
+        /// </summary>
+        /// <param name="disposable">The object to be disposed.</param>
         public virtual void RegisterForDispose(IDisposable disposable) => OnCompleted(_disposeDelegate, disposable);
 
+        /// <summary>
+        /// Adds a delegate to be invoked after the response has finished being sent to the client.
+        /// </summary>
+        /// <param name="callback">The delegate to invoke.</param>
         public virtual void OnCompleted(Func<Task> callback) => OnCompleted(_callbackDelegate, callback);
 
+        /// <summary>
+        /// Returns a temporary redirect response (HTTP 302) to the client.
+        /// </summary>
+        /// <param name="location">The URL to redirect the client to.</param>
         public virtual void Redirect(string location) => Redirect(location, permanent: false);
 
+        /// <summary>
+        /// Returns a redirect response (HTTP 301 or HTTP 302) to the client.
+        /// </summary>
+        /// <param name="location">The URL to redirect the client to.</param>
+        /// <param name="permanent"><c>True</c> if the redirect is permanent (301), otherwise <c>false</c> (302).</param>
         public abstract void Redirect(string location, bool permanent);
     }
 }

src/Microsoft.AspNet.Http.Abstractions/IApplicationBuilder.cs

@@ -7,18 +7,44 @@ using Microsoft.AspNet.Http.Features;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Defines a class that provides the mechanisms to configure an application's request pipeline.
+    /// </summary>
     public interface IApplicationBuilder
     {
+        /// <summary>
+        /// Gets or sets the <see cref="IServiceProvider"/> that provides access to the application's service container.
+        /// </summary>
         IServiceProvider ApplicationServices { get; set; }
 
+        /// <summary>
+        /// Gets the set of HTTP features the application's server provides.
+        /// </summary>
         IFeatureCollection ServerFeatures { get; }
 
+        /// <summary>
+        /// Gets a key/value collection that can be used to share data between middleware.
+        /// </summary>
         IDictionary<string, object> Properties { get; }
 
+        /// <summary>
+        /// Adds a middleware delegate to the application's request pipeline.
+        /// </summary>
+        /// <param name="middleware">The middleware delgate.</param>
+        /// <returns>The <see cref="IApplicationBuilder"/>.</returns>
         IApplicationBuilder Use(Func<RequestDelegate, RequestDelegate> middleware);
 
+        /// <summary>
+        /// Creates a new <see cref="IApplicationBuilder"/> that shares the <see cref="Properties"/> of this
+        /// <see cref="IApplicationBuilder"/>.
+        /// </summary>
+        /// <returns>The new <see cref="IApplicationBuilder"/>.</returns>
         IApplicationBuilder New();
 
+        /// <summary>
+        /// Builds the delegate used by this application to process HTTP requests.
+        /// </summary>
+        /// <returns>The request handling delegate.</returns>
         RequestDelegate Build();
     }
 }

src/Microsoft.AspNet.Http.Abstractions/RequestDelegate.cs

@@ -6,5 +6,10 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// A function that can process an HTTP request.
+    /// </summary>
+    /// <param name="context">The <see cref="HttpContext"/> for the request.</param>
+    /// <returns>A task that represents the completion of request processing.</returns>
     public delegate Task RequestDelegate(HttpContext context);
 }

src/Microsoft.AspNet.Http.Abstractions/WebSocketManager.cs

@@ -7,17 +7,35 @@ using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Http
 {
+    /// <summary>
+    /// Manages the establishment of WebSocket connections for a specific HTTP request. 
+    /// </summary>
     public abstract class WebSocketManager
     {
+        /// <summary>
+        /// Gets a value indicating whether the request is a WebSocket establishment request.
+        /// </summary>
         public abstract bool IsWebSocketRequest { get; }
 
+        /// <summary>
+        /// Gets the list of requested WebSocket sub-protocols.
+        /// </summary>
         public abstract IList<string> WebSocketRequestedProtocols { get; }
 
+        /// <summary>
+        /// Transitions the request to a WebSocket connection.
+        /// </summary>
+        /// <returns>A task representing the completion of the transition.</returns>
         public virtual Task<WebSocket> AcceptWebSocketAsync()
         {
             return AcceptWebSocketAsync(subProtocol: null);
         }
 
+        /// <summary>
+        /// Transitions the request to a WebSocket connection using the specified sub-protocol.
+        /// </summary>
+        /// <param name="subProtocol">The sub-protocol to use.</param>
+        /// <returns>A task representing the completion of the transition.</returns>
         public abstract Task<WebSocket> AcceptWebSocketAsync(string subProtocol);
     }
 }

src/Microsoft.AspNet.Http.Features/IFeatureCollection.cs

@@ -6,6 +6,9 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNet.Http.Features
 {
+    /// <summary>
+    /// Represents a collection of HTTP features.
+    /// </summary>
     public interface IFeatureCollection : IEnumerable<KeyValuePair<Type, object>>
     {
         /// <summary>
@@ -14,7 +17,7 @@ namespace Microsoft.AspNet.Http.Features
         bool IsReadOnly { get; }
 
         /// <summary>
-        /// Incremented for each modification and can be used verify cached results.
+        /// Incremented for each modification and can be used to verify cached results.
         /// </summary>
         int Revision { get; }