Add doc-comments for main APIs

- Coherence-Signed#75

Author: DamianEdwards

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

@@ -16,10 +16,10 @@ public static class HttpResponseWritingExtensions
         /// <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 @@ public static class HttpResponseWritingExtensions
         /// <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 @@
 
 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 @@ public static IApplicationBuilder Map(this IApplicationBuilder app, PathString p
             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 @@
 
 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 @@ public MapMiddleware(RequestDelegate next, MapOptions options)
             _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 @@
 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 @@
 
 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 @@ public MapWhenMiddleware(RequestDelegate next, MapWhenOptions options)
             _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 @@
 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 @@ public Func<HttpContext, bool> Predicate
         }
 
         /// <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 @@
 
 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 @@
 
 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 @@
 
 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 @@ public static IApplicationBuilder UseMiddleware(this IApplicationBuilder 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 @@
 
 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 @@
 
 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>