Add XML docs to endpoint route builder and extensions (#6700)

Author: JamesNK

src/Http/Routing/src/Builder/EndpointRouteBuilderExtensions.cs

@@ -10,6 +10,9 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Provides extension methods for <see cref="IEndpointRouteBuilder"/> to add endpoints.
+    /// </summary>
     public static class EndpointRouteBuilderExtensions
     {
         // Avoid creating a new array every call
@@ -19,6 +22,15 @@ public static class EndpointRouteBuilderExtensions
         private static readonly string[] DeleteVerb = new[] { "DELETE" };
 
         #region MapVerbs
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP GET requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapGet(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -28,6 +40,16 @@ public static IEndpointConventionBuilder MapGet(
             return MapVerbs(builder, pattern, displayName: null, requestDelegate, GetVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP GET requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapGet(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -38,6 +60,15 @@ public static IEndpointConventionBuilder MapGet(
             return MapVerbs(builder, pattern, displayName, requestDelegate, GetVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP POST requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapPost(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -47,6 +78,16 @@ public static IEndpointConventionBuilder MapPost(
             return MapVerbs(builder, pattern, displayName: null, requestDelegate, PostVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP POST requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapPost(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -57,6 +98,15 @@ public static IEndpointConventionBuilder MapPost(
             return MapVerbs(builder, pattern, displayName, requestDelegate, PostVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP PUT requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapPut(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -66,6 +116,16 @@ public static IEndpointConventionBuilder MapPut(
             return MapVerbs(builder, pattern, displayName: null, requestDelegate, PutVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP PUT requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapPut(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -76,6 +136,15 @@ public static IEndpointConventionBuilder MapPut(
             return MapVerbs(builder, pattern, displayName, requestDelegate, PutVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP DELETE requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapDelete(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -85,6 +154,16 @@ public static IEndpointConventionBuilder MapDelete(
             return MapVerbs(builder, pattern, displayName: null, requestDelegate, DeleteVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP DELETE requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapDelete(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -95,6 +174,16 @@ public static IEndpointConventionBuilder MapDelete(
             return MapVerbs(builder, pattern, displayName, requestDelegate, DeleteVerb, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified HTTP methods and pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="httpMethods">HTTP methods that the endpoint will match.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapVerbs(
            this IEndpointRouteBuilder builder,
            string pattern,
@@ -105,6 +194,17 @@ public static IEndpointConventionBuilder MapVerbs(
             return MapVerbs(builder, pattern, displayName: null, requestDelegate, httpMethods, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified HTTP methods and pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="httpMethods">HTTP methods that the endpoint will match.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder MapVerbs(
            this IEndpointRouteBuilder builder,
            string pattern,
@@ -130,6 +230,15 @@ public static IEndpointConventionBuilder MapVerbs(
         #endregion
 
         #region Map
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder Map(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -139,6 +248,16 @@ public static IEndpointConventionBuilder Map(
             return Map(builder, RoutePatternFactory.Parse(pattern), pattern, requestDelegate, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder Map(
             this IEndpointRouteBuilder builder,
             string pattern,
@@ -149,6 +268,15 @@ public static IEndpointConventionBuilder Map(
             return Map(builder, RoutePatternFactory.Parse(pattern), displayName, requestDelegate, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder Map(
             this IEndpointRouteBuilder builder,
             RoutePattern pattern,
@@ -158,6 +286,16 @@ public static IEndpointConventionBuilder Map(
             return Map(builder, pattern, pattern.RawText ?? pattern.DebuggerToString(), requestDelegate, metadata);
         }
 
+        /// <summary>
+        /// Adds a <see cref="RouteEndpoint"/> to the <see cref="IEndpointRouteBuilder"/> that matches HTTP requests
+        /// for the specified pattern.
+        /// </summary>
+        /// <param name="builder">The <see cref="IEndpointRouteBuilder"/> to add the route to.</param>
+        /// <param name="pattern">The route pattern.</param>
+        /// <param name="displayName">The display name for the endpoint.</param>
+        /// <param name="requestDelegate">The delegate executed when the endpoint is matched.</param>
+        /// <param name="metadata">Metadata that is added to the endpoint.</param>
+        /// <returns>A <see cref="IEndpointConventionBuilder"/> that can be used to further customize the endpoint.</returns>
         public static IEndpointConventionBuilder Map(
             this IEndpointRouteBuilder builder,
             RoutePattern pattern,

src/Http/Routing/src/IEndpointRouteBuilder.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -7,12 +7,26 @@
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Defines a contract for a route builder in an application. A route builder specifies the routes for
+    /// an application.
+    /// </summary>
     public interface IEndpointRouteBuilder
     {
+        /// <summary>
+        /// Creates a new <see cref="IApplicationBuilder"/>.
+        /// </summary>
+        /// <returns>The new <see cref="IApplicationBuilder"/>.</returns>
         IApplicationBuilder CreateApplicationBuilder();
 
+        /// <summary>
+        /// Gets the sets the <see cref="IServiceProvider"/> used to resolve services for routes.
+        /// </summary>
         IServiceProvider ServiceProvider { get; }
 
+        /// <summary>
+        /// Gets the endpoint data sources configured in the builder.
+        /// </summary>
         ICollection<EndpointDataSource> DataSources { get; }
     }
-}
+}