From c0242240f825870735bdb12f2811aa4750adf731 Mon Sep 17 00:00:00 2001 From: Eilon Lipton Date: Mon, 19 Oct 2015 11:21:31 -0700 Subject: [PATCH] Adding doc comments for frequently used APIs Some copied from older docs. Also renamed BuilderExtensions type to a more specific name. --- .../BuilderExtensions.cs | 11 ++- src/Microsoft.AspNet.Routing/IRouteBuilder.cs | 12 +++ .../IRouteConstraint.cs | 12 +++ .../RouteBuilderExtensions.cs | 77 ++++++++++++++----- .../RouteDirection.cs | 10 +++ 5 files changed, 101 insertions(+), 21 deletions(-) diff --git a/src/Microsoft.AspNet.Routing/BuilderExtensions.cs b/src/Microsoft.AspNet.Routing/BuilderExtensions.cs index ebc409f128..4fabffefbe 100644 --- a/src/Microsoft.AspNet.Routing/BuilderExtensions.cs +++ b/src/Microsoft.AspNet.Routing/BuilderExtensions.cs @@ -6,8 +6,17 @@ using Microsoft.AspNet.Routing; namespace Microsoft.AspNet.Builder { - public static class BuilderExtensions + /// + /// Extension methods for adding the middleware to an . + /// + public static class RoutingBuilderExtensions { + /// + /// Adds a middleware to the specified with the specified . + /// + /// The to add the middleware to. + /// The to use for routing requests. + /// A reference to this instance after the operation has completed. public static IApplicationBuilder UseRouter(this IApplicationBuilder builder, IRouter router) { if (builder == null) diff --git a/src/Microsoft.AspNet.Routing/IRouteBuilder.cs b/src/Microsoft.AspNet.Routing/IRouteBuilder.cs index ba9798bd7c..a1b9ee5a24 100644 --- a/src/Microsoft.AspNet.Routing/IRouteBuilder.cs +++ b/src/Microsoft.AspNet.Routing/IRouteBuilder.cs @@ -6,14 +6,26 @@ using System.Collections.Generic; namespace Microsoft.AspNet.Routing { + /// + /// Defines a contract for a route builder in an application. A route builder specifies the routes for an application. + /// public interface IRouteBuilder { + /// + /// Gets or sets the default that is used if an is added to the list of routes but does not specify its own. + /// IRouter DefaultHandler { get; set; } IServiceProvider ServiceProvider { get; } + /// + /// Gets the routes configured in the builder. + /// IList Routes { get; } + /// + /// Builds an that routes the routes specified in the property. + /// IRouter Build(); } } \ No newline at end of file diff --git a/src/Microsoft.AspNet.Routing/IRouteConstraint.cs b/src/Microsoft.AspNet.Routing/IRouteConstraint.cs index ac1558e6a1..10664c21cc 100644 --- a/src/Microsoft.AspNet.Routing/IRouteConstraint.cs +++ b/src/Microsoft.AspNet.Routing/IRouteConstraint.cs @@ -6,8 +6,20 @@ using Microsoft.AspNet.Http; namespace Microsoft.AspNet.Routing { + /// + /// Defines the contract that a class must implement in order to check whether a URL parameter value is valid for a constraint. + /// public interface IRouteConstraint { + /// + /// Determines whether the URL parameter contains a valid value for this constraint. + /// + /// An object that encapsulates information about the HTTP request. + /// The router that this constraint belongs to. + /// The name of the parameter that is being checked. + /// A dictionary that contains the parameters for the URL. + /// 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. + /// true if the URL parameter contains a valid value; otherwise, false. bool Match(HttpContext httpContext, IRouter route, string routeKey, diff --git a/src/Microsoft.AspNet.Routing/RouteBuilderExtensions.cs b/src/Microsoft.AspNet.Routing/RouteBuilderExtensions.cs index 1b3091c7b8..07d24d34c9 100644 --- a/src/Microsoft.AspNet.Routing/RouteBuilderExtensions.cs +++ b/src/Microsoft.AspNet.Routing/RouteBuilderExtensions.cs @@ -9,57 +9,94 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNet.Builder { + /// + /// Provides extension methods for to add routes. + /// public static class RouteBuilderExtensions { - public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder, + /// + /// Adds a route to the with the specified name and template. + /// + /// The to add the route to. + /// The name of the route. + /// The URL pattern of the route. + /// A reference to this instance after the operation has completed. + public static IRouteBuilder MapRoute(this IRouteBuilder routeBuilder, string name, string template) { - MapRoute(routeCollectionBuilder, name, template, defaults: null); - return routeCollectionBuilder; + MapRoute(routeBuilder, name, template, defaults: null); + return routeBuilder; } - public static IRouteBuilder MapRoute(this IRouteBuilder routeCollectionBuilder, + /// + /// Adds a route to the with the specified name, template, and default values. + /// + /// The to add the route to. + /// The name of the route. + /// The URL pattern of the route. + /// An object that contains default values for route parameters. The object's properties represent the names and values of the default values. + /// A reference to this instance after the operation has completed. + 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, + /// + /// Adds a route to the with the specified name, template, default values, and constraints. + /// + /// The to add the route to. + /// The name of the route. + /// The URL pattern of the route. + /// An object that contains default values for route parameters. The object's properties represent the names and values of the default values. + /// An object that contains constraints for the route. The object's properties represent the names and values of the constraints. + /// A reference to this instance after the operation has completed. + 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, + /// + /// Adds a route to the with the specified name, template, default values, and data tokens. + /// + /// The to add the route to. + /// The name of the route. + /// The URL pattern of the route. + /// An object that contains default values for route parameters. The object's properties represent the names and values of the default values. + /// An object that contains constraints for the route. The object's properties represent the names and values of the constraints. + /// An object that contains data tokens for the route. The object's properties represent the names and values of the data tokens. + /// A reference to this instance after the operation has completed. + 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 - .ServiceProvider - .GetRequiredService(); - routeCollectionBuilder.Routes.Add(new TemplateRoute(routeCollectionBuilder.DefaultHandler, - name, - template, - ObjectToDictionary(defaults), - ObjectToDictionary(constraints), - ObjectToDictionary(dataTokens), - inlineConstraintResolver)); + var inlineConstraintResolver = routeBuilder + .ServiceProvider + .GetRequiredService(); + routeBuilder.Routes.Add(new TemplateRoute(routeBuilder.DefaultHandler, + name, + template, + ObjectToDictionary(defaults), + ObjectToDictionary(constraints), + ObjectToDictionary(dataTokens), + inlineConstraintResolver)); - return routeCollectionBuilder; + return routeBuilder; } private static IDictionary ObjectToDictionary(object value) diff --git a/src/Microsoft.AspNet.Routing/RouteDirection.cs b/src/Microsoft.AspNet.Routing/RouteDirection.cs index 4dbfdef911..316d085164 100644 --- a/src/Microsoft.AspNet.Routing/RouteDirection.cs +++ b/src/Microsoft.AspNet.Routing/RouteDirection.cs @@ -3,9 +3,19 @@ namespace Microsoft.AspNet.Routing { + /// + /// Indicates whether ASP.NET routing is processing a URL from an HTTP request or generating a URL. + /// public enum RouteDirection { + /// + /// A URL from a client is being processed. + /// IncomingRequest, + + /// + /// A URL is being created based on the route definition. + /// UrlGeneration, } }