Add documentation for Routing surface area (#26513)

* Add documentation for Routing surface area

* Apply suggestions from code review

Co-authored-by: James Newton-King <[email protected]>

* Fix up some doc strings

Co-authored-by: James Newton-King <[email protected]>

Author: captainsafia

src/Http/Http.Abstractions/src/StatusCodes.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.AspNetCore.Http
 {
     /// <summary>
-    /// A collection of contants for HTTP status codes.
+    /// A collection of constants for HTTP status codes.
     ///
     /// Status Codes listed at http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
     /// </summary>

src/Http/Routing.Abstractions/src/IRouteHandler.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.AspNetCore.Routing
 {
     /// <summary>
-    /// Defines a contract for a handler of a route. 
+    /// Defines a contract for a handler of a route.
     /// </summary>
     public interface IRouteHandler
     {

src/Http/Routing.Abstractions/src/IRouter.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.AspNetCore.Routing
 {
     /// <summary>
-    ///
+    /// Interface for implementing a router.
     /// </summary>
     public interface IRouter
     {

src/Http/Routing/perf/Matching/MatcherBuilderMultipleEntryBenchmark.cs

@@ -205,4 +205,4 @@ public int Compare(Endpoint x, Endpoint y)
             }
         }
     }
-}
+}

src/Http/Routing/src/Builder/EndpointRoutingApplicationBuilderExtensions.cs

@@ -9,6 +9,9 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Constains extensions for configuring routing on an <see cref="IApplicationBuilder"/>.
+    /// </summary>
     public static class EndpointRoutingApplicationBuilderExtensions
     {
         private const string EndpointRouteBuilder = "__EndpointRouteBuilder";

src/Http/Routing/src/CompositeEndpointDataSource.cs

@@ -40,6 +40,11 @@ internal CompositeEndpointDataSource(ObservableCollection<EndpointDataSource> da
             _dataSources = dataSources;
         }
 
+        /// <summary>
+        /// Instantiates a <see cref="CompositeEndpointDataSource"/> object from <paramref name="endpointDataSources"/>.
+        /// </summary>
+        /// <param name="endpointDataSources">An collection of <see cref="EndpointDataSource" /> objects.</param>
+        /// <returns>A <see cref="CompositeEndpointDataSource"/> </returns>
         public CompositeEndpointDataSource(IEnumerable<EndpointDataSource> endpointDataSources) : this()
         {
             _dataSources = new List<EndpointDataSource>();
@@ -62,6 +67,9 @@ private void OnDataSourcesChanged(object? sender, NotifyCollectionChangedEventAr
             }
         }
 
+        /// <summary>
+        /// Returns the collection of <see cref="EndpointDataSource"/> instances associated with the object.
+        /// </summary>
         public IEnumerable<EndpointDataSource> DataSources => _dataSources;
 
         /// <summary>
@@ -123,12 +131,12 @@ private void HandleChange()
                 // Refresh the endpoints from datasource so that callbacks can get the latest endpoints
                 _endpoints = _dataSources.SelectMany(d => d.Endpoints).ToArray();
 
-                // Prevent consumers from re-registering callback to inflight events as that can 
+                // Prevent consumers from re-registering callback to inflight events as that can
                 // cause a stackoverflow
                 // Example:
                 // 1. B registers A
                 // 2. A fires event causing B's callback to get called
-                // 3. B executes some code in its callback, but needs to re-register callback 
+                // 3. B executes some code in its callback, but needs to re-register callback
                 //    in the same callback
                 var oldTokenSource = _cts;
                 var oldToken = _consumerChangeToken;

src/Http/Routing/src/Constraints/OptionalRouteConstraint.cs

@@ -7,10 +7,14 @@
 namespace Microsoft.AspNetCore.Routing.Constraints
 {
     /// <summary>
-    /// Defines a constraint on an optional parameter. If the parameter is present, then it is constrained by InnerConstraint. 
+    /// Defines a constraint on an optional parameter. If the parameter is present, then it is constrained by InnerConstraint.
     /// </summary>
     public class OptionalRouteConstraint : IRouteConstraint
     {
+        /// <summary>
+        /// Creates a new <see cref="OptionalRouteConstraint"/> instance given the <paramref name="innerConstraint"/>.
+        /// </summary>
+        /// <param name="innerConstraint"></param>
         public OptionalRouteConstraint(IRouteConstraint innerConstraint)
         {
             if (innerConstraint == null)
@@ -21,8 +25,12 @@ public OptionalRouteConstraint(IRouteConstraint innerConstraint)
             InnerConstraint = innerConstraint;
         }
 
+        /// <summary>
+        /// Gets the <see cref="IRouteConstraint"/> associated with the optional parameter.
+        /// </summary>
         public IRouteConstraint InnerConstraint { get; }
 
+        /// <inheritdoc />
         public bool Match(
             HttpContext? httpContext,
             IRouter? route,

src/Http/Routing/src/Constraints/RegexRouteConstraint.cs

@@ -8,10 +8,17 @@
 
 namespace Microsoft.AspNetCore.Routing.Constraints
 {
+    /// <summary>
+    /// Constrains a route parameter to match a regular expression.
+    /// </summary>
     public class RegexRouteConstraint : IRouteConstraint
     {
         private static readonly TimeSpan RegexMatchTimeout = TimeSpan.FromSeconds(10);
 
+        /// <summary>
+        /// Constructor for a <see cref="RegexRouteConstraint"/> given a <paramref name="regex"/>.
+        /// </summary>
+        /// <param name="regex">A <see cref="Regex"/> instance to use as a constraint.</param>
         public RegexRouteConstraint(Regex regex)
         {
             if (regex == null)
@@ -22,6 +29,10 @@ public RegexRouteConstraint(Regex regex)
             Constraint = regex;
         }
 
+        /// <summary>
+        /// Constructor for a <see cref="RegexRouteConstraint"/> given a <paramref name="regexPattern"/>.
+        /// </summary>
+        /// <param name="regexPattern">A string containing the regex pattern.</param>
         public RegexRouteConstraint(string regexPattern)
         {
             if (regexPattern == null)
@@ -35,8 +46,12 @@ public RegexRouteConstraint(string regexPattern)
                 RegexMatchTimeout);
         }
 
+        /// <summary>
+        /// Gets the regular expression used in the route constraint.
+        /// </summary>
         public Regex Constraint { get; private set; }
 
+        /// <inheritdoc />
         public bool Match(
             HttpContext? httpContext,
             IRouter? route,

src/Http/Routing/src/DataTokensMetadata.cs

@@ -14,6 +14,10 @@ namespace Microsoft.AspNetCore.Routing
     /// </summary>
     public sealed class DataTokensMetadata : IDataTokensMetadata
     {
+        /// <summary>
+        /// Constructor for a new <see cref="DataTokensMetadata"/> given <paramref name="dataTokens"/>.
+        /// </summary>
+        /// <param name="dataTokens">The data tokens.</param>
         public DataTokensMetadata(IReadOnlyDictionary<string, object> dataTokens)
         {
             if (dataTokens == null)

src/Http/Routing/src/INamedRouter.cs

@@ -3,8 +3,14 @@
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// An interface for an <see cref="IRouter"/> with a name.
+    /// </summary>
     public interface INamedRouter : IRouter
     {
+        /// <summary>
+        /// The name of the router. Can be null.
+        /// </summary>
         string? Name { get; }
     }
 }