Adding doc comments for frequently used APIs

Some copied from older docs.
Also renamed BuilderExtensions type to a more specific name.

src/Microsoft.AspNet.Routing/BuilderExtensions.cs

@@ -6,8 +6,17 @@ using Microsoft.AspNet.Routing;
 
 namespace Microsoft.AspNet.Builder
 {
-    public static class BuilderExtensions
+    /// <summary>
+    /// Extension methods for adding the <see cref="RouterMiddleware"/> middleware to an <see cref="IApplicationBuilder"/>.
+    /// </summary>
+    public static class RoutingBuilderExtensions
     {
+        /// <summary>
+        /// Adds a <see cref="RouterMiddleware"/> middleware to the specified <see cref="IApplicationBuilder"/> with the specified <see cref="IRouter"/>.
+        /// </summary>
+        /// <param name="builder">The <see cref="IApplicationBuilder"/> to add the middleware to.</param>
+        /// <param name="router">The <see cref="IRouter"/> to use for routing requests.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
         public static IApplicationBuilder UseRouter(this IApplicationBuilder builder, IRouter router)
         {
             if (builder == null)

src/Microsoft.AspNet.Routing/IRouteBuilder.cs

@@ -6,14 +6,26 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNet.Routing
 {
+    /// <summary>
+    /// Defines a contract for a route builder in an application. A route builder specifies the routes for an application.
+    /// </summary>
     public interface IRouteBuilder
     {
+        /// <summary>
+        /// Gets or sets the default <see cref="IRouter"/> that is used if an <see cref="IRouter"/> is added to the list of routes but does not specify its own.
+        /// </summary>
         IRouter DefaultHandler { get; set; }
 
         IServiceProvider ServiceProvider { get; }
 
+        /// <summary>
+        /// Gets the routes configured in the builder.
+        /// </summary>
         IList<IRouter> Routes { get; }
 
+        /// <summary>
+        /// Builds an <see cref="IRouter"/> that routes the routes specified in the <see cref="Routes"/> property.
+        /// </summary>
         IRouter Build();
     }
 }

src/Microsoft.AspNet.Routing/IRouteConstraint.cs

@@ -6,8 +6,20 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Routing
 {
+    /// <summary>
+    /// Defines the contract that a class must implement in order to check whether a URL parameter value is valid for a constraint.
+    /// </summary>
     public interface IRouteConstraint
     {
+        /// <summary>
+        /// Determines whether the URL parameter contains a valid value for this constraint.
+        /// </summary>
+        /// <param name="httpContext">An object that encapsulates information about the HTTP request.</param>
+        /// <param name="route">The router that this constraint belongs to.</param>
+        /// <param name="routeKey">The name of the parameter that is being checked.</param>
+        /// <param name="values">A dictionary that contains the parameters for the URL.</param>
+        /// <param name="routeDirection">An object that indicates whether the constraint check is being performed when an incoming request is being handled or when a URL is being generated.</param>
+        /// <returns><c>true</c> if the URL parameter contains a valid value; otherwise, <c>false</c>.</returns>
         bool Match(HttpContext httpContext,
                    IRouter route,
                    string routeKey,

src/Microsoft.AspNet.Routing/RouteBuilderExtensions.cs

@@ -9,57 +9,94 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// Provides extension methods for <see cref="IRouteBuilder"/> to add routes.
+    /// </summary>
     public static class RouteBuilderExtensions
     {
-        public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder,
+        /// <summary>
+        /// Adds a route to the <see cref="IRouteBuilder"/> with the specified name and template.
+        /// </summary>
+        /// <param name="routeBuilder">The <see cref="IRouteBuilder"/> to add the route to.</param>
+        /// <param name="name">The name of the route.</param>
+        /// <param name="template">The URL pattern of the route.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
+        public static IRouteBuilder MapRoute(this IRouteBuilder routeBuilder,
                                              string name,
                                              string template)
         {
-            MapRoute(routeCollectionBuilder, name, template, defaults: null);
+            MapRoute(routeBuilder, name, template, defaults: null);
-            return routeCollectionBuilder;
+            return routeBuilder;
         }
 
-        public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder,
+        /// <summary>
+        /// Adds a route to the <see cref="IRouteBuilder"/> with the specified name, template, and default values.
+        /// </summary>
+        /// <param name="routeBuilder">The <see cref="IRouteBuilder"/> to add the route to.</param>
+        /// <param name="name">The name of the route.</param>
+        /// <param name="template">The URL pattern of the route.</param>
+        /// <param name="defaults">An object that contains default values for route parameters. The object's properties represent the names and values of the default values.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
+        public static IRouteBuilder MapRoute(this IRouteBuilder routeBuilder,
                                              string name,
                                              string template,
                                              object defaults)
         {
-            return MapRoute(routeCollectionBuilder, name, template, defaults, constraints: null);
+            return MapRoute(routeBuilder, name, template, defaults, constraints: null);
         }
 
-        public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder,
+        /// <summary>
+        /// Adds a route to the <see cref="IRouteBuilder"/> with the specified name, template, default values, and constraints.
+        /// </summary>
+        /// <param name="routeBuilder">The <see cref="IRouteBuilder"/> to add the route to.</param>
+        /// <param name="name">The name of the route.</param>
+        /// <param name="template">The URL pattern of the route.</param>
+        /// <param name="defaults">An object that contains default values for route parameters. The object's properties represent the names and values of the default values.</param>
+        /// <param name="constraints">An object that contains constraints for the route. The object's properties represent the names and values of the constraints.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
+        public static IRouteBuilder MapRoute(this IRouteBuilder routeBuilder,
                                              string name,
                                              string template,
                                              object defaults,
                                              object constraints)
         {
-            return MapRoute(routeCollectionBuilder, name, template, defaults, constraints, dataTokens: null);
+            return MapRoute(routeBuilder, name, template, defaults, constraints, dataTokens: null);
         }
 
-        public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder,
+        /// <summary>
+        /// Adds a route to the <see cref="IRouteBuilder"/> with the specified name, template, default values, and data tokens.
+        /// </summary>
+        /// <param name="routeBuilder">The <see cref="IRouteBuilder"/> to add the route to.</param>
+        /// <param name="name">The name of the route.</param>
+        /// <param name="template">The URL pattern of the route.</param>
+        /// <param name="defaults">An object that contains default values for route parameters. The object's properties represent the names and values of the default values.</param>
+        /// <param name="constraints">An object that contains constraints for the route. The object's properties represent the names and values of the constraints.</param>
+        /// <param name="dataTokens">An object that contains data tokens for the route. The object's properties represent the names and values of the data tokens.</param>
+        /// <returns>A reference to this instance after the operation has completed.</returns>
+        public static IRouteBuilder MapRoute(this IRouteBuilder routeBuilder,
                                              string name,
                                              string template,
                                              object defaults,
                                              object constraints,
                                              object dataTokens)
         {
-            if (routeCollectionBuilder.DefaultHandler == null)
+            if (routeBuilder.DefaultHandler == null)
             {
                 throw new InvalidOperationException(Resources.DefaultHandler_MustBeSet);
             }
 
-            var inlineConstraintResolver = routeCollectionBuilder
+            var inlineConstraintResolver = routeBuilder
-                                                        .ServiceProvider
+                                           .ServiceProvider
-                                                        .GetRequiredService<IInlineConstraintResolver>();
+                                           .GetRequiredService<IInlineConstraintResolver>();
-            routeCollectionBuilder.Routes.Add(new TemplateRoute(routeCollectionBuilder.DefaultHandler,
+            routeBuilder.Routes.Add(new TemplateRoute(routeBuilder.DefaultHandler,
-                                                                name,
+                                                      name,
-                                                                template,
+                                                      template,
-                                                                ObjectToDictionary(defaults),
+                                                      ObjectToDictionary(defaults),
-                                                                ObjectToDictionary(constraints),
+                                                      ObjectToDictionary(constraints),
-                                                                ObjectToDictionary(dataTokens),
+                                                      ObjectToDictionary(dataTokens),
-                                                                inlineConstraintResolver));
+                                                      inlineConstraintResolver));
 
-            return routeCollectionBuilder;
+            return routeBuilder;
         }
 
         private static IDictionary<string, object> ObjectToDictionary(object value)

src/Microsoft.AspNet.Routing/RouteDirection.cs

@@ -3,9 +3,19 @@
 
 namespace Microsoft.AspNet.Routing
 {
+    /// <summary>
+    /// Indicates whether ASP.NET routing is processing a URL from an HTTP request or generating a URL.
+    /// </summary>
     public enum RouteDirection
     {
+        /// <summary>
+        /// A URL from a client is being processed.
+        /// </summary>
         IncomingRequest,
+
+        /// <summary>
+        /// A URL is being created based on the route definition.
+        /// </summary>
         UrlGeneration,
     }
 }