adding more docs

src/Microsoft.AspNetCore.Routing/Matching/CandidateSet.cs

@@ -6,6 +6,11 @@ using System.Runtime.CompilerServices;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// Represents a set of <see cref="Endpoint"/> candidates that have been matched
+    /// by the routing system. Used by implementations of <see cref="EndpointSelector"/>
+    /// and <see cref="IEndpointSelectorPolicy"/>.
+    /// </summary>
     public sealed class CandidateSet
     {
         // We inline storage for 4 candidates here to avoid allocations in common
@@ -18,8 +23,18 @@ namespace Microsoft.AspNetCore.Routing.Matching
 
         private CandidateState[] _additionalCandidates;
 
-        // Provided to make testing possible/easy for someone implementing
+        /// <summary>
-        // an EndpointSelector.
+        /// <para>
+        /// Initializes a new instances of the candidate set structure with the provided list of endpoints 
+        /// and associated scores.
+        /// </para>
+        /// <para>
+        /// The constructor is provided to enable unit tests of implementations of <see cref="EndpointSelector"/>
+        /// and <see cref="IEndpointSelectorPolicy"/>.
+        /// </para>
+        /// </summary>
+        /// <param name="endpoints">The list of endpoints, sorted in descending priority order.</param>
+        /// <param name="scores">The list of endpoint scores. <see cref="CandidateState.Score"/>.</param>
         public CandidateSet(MatcherEndpoint[] endpoints, int[] scores)
         {
             Count = endpoints.Length;
@@ -112,12 +127,25 @@ namespace Microsoft.AspNetCore.Routing.Matching
             }
         }
 
+        /// <summary>
+        /// Gets the count of candidates in the set.
+        /// </summary>
         public int Count { get; }
 
-        // Note that this is a ref-return because of both mutability and performance.
+        /// <summary>
-        // We don't want to copy these fat structs if it can be avoided.
+        /// Gets the <see cref="CandidateState"/> associated with the candidate <see cref="Endpoint"/>
+        /// at <paramref name="index"/>.
+        /// </summary>
+        /// <param name="index">The candidate index.</param>
+        /// <returns>
+        /// A reference to the <see cref="CandidateState"/>. The result is returned by reference
+        /// and intended to be mutated.
+        /// </returns>
         public ref CandidateState this[int index]
         {
+            // Note that this is a ref-return because of both mutability and performance.
+            // We don't want to copy these fat structs if it can be avoided.
+
             // PERF: Force inlining
             [MethodImpl(MethodImplOptions.AggressiveInlining)]
             get

src/Microsoft.AspNetCore.Routing/Matching/CandidateState.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// The mutable state associated with a candidate in a <see cref="CandidateSet"/>.
+    /// </summary>
     public struct CandidateState
     {
         internal CandidateState(MatcherEndpoint endpoint, int score)
@@ -14,12 +17,39 @@ namespace Microsoft.AspNetCore.Routing.Matching
             Values = null;
         }
 
+        /// <summary>
+        /// Gets the <see cref="Routing.Endpoint"/>.
+        /// </summary>
         public MatcherEndpoint Endpoint { get; }
 
+        /// <summary>
+        /// Gets the score of the <see cref="Routing.Endpoint"/> within the current
+        /// <see cref="CandidateSet"/>.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Candidates within a set are ordered in priority order and then assigned a
+        /// sequential score value based on that ordering. Candiates with the same
+        /// score are considered to have equal priority.
+        /// </para>
+        /// <para>
+        /// The score values are used in the <see cref="EndpointSelector"/> to determine
+        /// whether a set of matching candidates is an ambiguous match.
+        /// </para>
+        /// </remarks>
         public int Score { get; }
 
+        /// <summary>
+        /// Gets or sets a value which indicates where the <see cref="Routing.Endpoint"/> is considered
+        /// a valid candiate for the current request. Set this value to <c>false</c> to exclude an
+        /// <see cref="Routing.Endpoint"/> from consideration.
+        /// </summary>
         public bool IsValidCandidate { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="RouteValueDictionary"/> associated with the
+        /// <see cref="Routing.Endpoint"/> and the current request.
+        /// </summary>
         public RouteValueDictionary Values { get; set; }
     }
 }

src/Microsoft.AspNetCore.Routing/Matching/EndpointMetadataComparer.cs

@@ -6,10 +6,30 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// A base class for <see cref="IComparer{Endpoint}"/> implementations that use 
+    /// a specific type of metadata from <see cref="Endpoint.Metadata"/> for comparison.
+    /// Useful for implementing <see cref="IEndpointComparerPolicy.Comparer"/>.
+    /// </summary>
+    /// <typeparam name="TMetadata">
+    /// The type of metadata to compare. Typically this is a type of metadata related
+    /// to the application concern being handled.
+    /// </typeparam>
     public abstract class EndpointMetadataComparer<TMetadata> : IComparer<Endpoint> where TMetadata : class
     {
         public static readonly EndpointMetadataComparer<TMetadata> Default = new DefaultComparer<TMetadata>();
 
+        /// <summary>
+        /// Compares two objects and returns a value indicating whether one is less than, equal to, 
+        /// or greater than the other.
+        /// </summary>
+        /// <param name="x">The first object to compare.</param>
+        /// <param name="y">The second object to compare.</param>
+        /// <returns>
+        /// An implementation of this method must return a value less than zero if 
+        /// x is less than y, zero if x is equal to y, or a value greater than zero if x is 
+        /// greater than y.
+        /// </returns>
         public int Compare(Endpoint x, Endpoint y)
         {
             if (x == null)
@@ -25,11 +45,32 @@ namespace Microsoft.AspNetCore.Routing.Matching
             return CompareMetadata(GetMetadata(x), GetMetadata(y));
         }
 
+        /// <summary>
+        /// Gets the metadata of type <typeparamref name="TMetadata"/> from the provided endpoint.
+        /// </summary>
+        /// <param name="endpoint">The <see cref="Endpoint"/>.</param>
+        /// <returns>The <typeparamref name="TMetadata"/> instance or <c>null</c>.</returns>
         protected virtual TMetadata GetMetadata(Endpoint endpoint)
         {
             return endpoint.Metadata.GetMetadata<TMetadata>();
         }
 
+        /// <summary>
+        /// Compares two <typeparamref name="TMetadata"/> instances.
+        /// </summary>
+        /// <param name="x">The first object to compare.</param>
+        /// <param name="y">The second object to compare.</param>
+        /// <returns>
+        /// An implementation of this method must return a value less than zero if 
+        /// x is less than y, zero if x is equal to y, or a value greater than zero if x is 
+        /// greater than y.
+        /// </returns>
+        /// <remarks>
+        /// The base-class implementation of this method will compare metadata based on whether
+        /// or not they are <c>null</c>. The effect of this is that when endpoints are being
+        /// compared, the endpoint that defines an instance of <typeparamref name="TMetadata"/>
+        /// will be considered higher priority.
+        /// </remarks>
         protected virtual int CompareMetadata(TMetadata x, TMetadata y)
         {
             // The default policy is that if x endpoint defines TMetadata, and

src/Microsoft.AspNetCore.Routing/Matching/EndpointSelector.cs

@@ -6,8 +6,25 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// A service that is responsible for the final <see cref="Endpoint"/> selection
+    /// decision. To use a custom <see cref="EndpointSelector"/> register an implementation
+    /// of <see cref="EndpointSelector"/> in the dependency injection container as a singleton.
+    /// </summary>
     public abstract class EndpointSelector
     {
+        /// <summary>
+        /// Asynchronously selects an <see cref="Endpoint"/> from the <see cref="CandidateSet"/>.
+        /// </summary>
+        /// <param name="httpContext">The <see cref="HttpContext"/> associated with the current request.</param>
+        /// <param name="feature">The <see cref="IEndpointFeature"/> associated with the current request.</param>
+        /// <param name="candidates">The <see cref="CandidateSet"/>.</param>
+        /// <returns>A <see cref="Task"/> that completes asynchronously once endpoint selection is complete.</returns>
+        /// <remarks>
+        /// An <see cref="EndpointSelector"/> should assign the <see cref="IEndpointFeature.Endpoint"/>,
+        /// <see cref="IEndpointFeature.Invoker"/>, and <see cref="IEndpointFeature.Values"/> properties
+        /// once an endpoint is selected.
+        /// </remarks>
         public abstract Task SelectAsync(
             HttpContext httpContext,
             IEndpointFeature feature,

src/Microsoft.AspNetCore.Routing/Matching/HttpMethodMatcherPolicy.cs

@@ -12,6 +12,10 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// An <see cref="MatcherPolicy"/> that implements filtering and selection by
+    /// the HTTP method of a request.
+    /// </summary>
     public sealed class HttpMethodMatcherPolicy : MatcherPolicy, IEndpointComparerPolicy, INodeBuilderPolicy
     {
         // Used in tests
@@ -25,12 +29,23 @@ namespace Microsoft.AspNetCore.Routing.Matching
         // Used in tests
         internal const string AnyMethod = "*";
 
+        /// <summary>
+        /// For framework use only.
+        /// </summary>
         public IComparer<Endpoint> Comparer => new HttpMethodMetadataEndpointComparer();
 
         // The order value is chosen to be less than 0, so that it comes before naively
         // written policies.
+        /// <summary>
+        /// For framework use only.
+        /// </summary>
         public override int Order => -1000;
 
+        /// <summary>
+        /// For framework use only.
+        /// </summary>
+        /// <param name="endpoints"></param>
+        /// <returns></returns>
         public bool AppliesToNode(IReadOnlyList<Endpoint> endpoints)
         {
             if (endpoints == null)
@@ -49,6 +64,11 @@ namespace Microsoft.AspNetCore.Routing.Matching
             return false;
         }
 
+        /// <summary>
+        /// For framework use only.
+        /// </summary>
+        /// <param name="endpoints"></param>
+        /// <returns></returns>
         public IReadOnlyList<PolicyNodeEdge> GetEdges(IReadOnlyList<Endpoint> endpoints)
         {
             // The algorithm here is designed to be preserve the order of the endpoints
@@ -180,6 +200,12 @@ namespace Microsoft.AspNetCore.Routing.Matching
             }
         }
 
+        /// <summary>
+        /// For framework use only.
+        /// </summary>
+        /// <param name="exitDestination"></param>
+        /// <param name="edges"></param>
+        /// <returns></returns>
         public PolicyJumpTable BuildJumpTable(int exitDestination, IReadOnlyList<PolicyJumpTableEdge> edges)
         {
             var destinations = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);

src/Microsoft.AspNetCore.Routing/Matching/IEndpointComparerPolicy.cs

@@ -5,8 +5,30 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// A <see cref="MatcherPolicy"/> interface that can be implemented to sort
+    /// endpoints. Implementations of <see cref="IEndpointComparerPolicy"/> must
+    /// inherit from <see cref="MatcherPolicy"/> and should be registered in
+    /// the dependency injection container as singleton services of type <see cref="MatcherPolicy"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Candidates in a <see cref="CandidateSet"/> are sorted based on their priority. Defining
+    /// a <see cref="IEndpointComparerPolicy"/> adds an additional criterion to the sorting
+    /// operation used to order candidates.
+    /// </para>
+    /// <para>
+    /// As an example, the implementation of <see cref="HttpMethodMatcherPolicy"/> implements
+    /// <see cref="IEndpointComparerPolicy"/> to ensure that endpoints matching specific HTTP
+    /// methods are sorted with a higher priority than endpoints without a specific HTTP method
+    /// requirement.
+    /// </para>
+    /// </remarks>
     public interface IEndpointComparerPolicy
     {
+        /// <summary>
+        /// Gets an <see cref="IComparer{Endpoint}"/> that will be used to sort the endpoints.
+        /// </summary>
         IComparer<Endpoint> Comparer { get; }
     }
 }

src/Microsoft.AspNetCore.Routing/Matching/IEndpointSelectorPolicy.cs

@@ -5,8 +5,26 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// A <see cref="MatcherPolicy"/> interface that can implemented to filter endpoints
+    /// in a <see cref="CandidateSet"/>. Implementations of <see cref="IEndpointSelectorPolicy"/> must
+    /// inherit from <see cref="MatcherPolicy"/> and should be registered in
+    /// the dependency injection container as singleton services of type <see cref="MatcherPolicy"/>.
+    /// </summary>
     public interface IEndpointSelectorPolicy
     {
+        /// <summary>
+        /// Applies the policy to the <see cref="CandidateSet"/>.
+        /// </summary>
+        /// <param name="httpContext">
+        /// The <see cref="HttpContext"/> associated with the current request.
+        /// </param>
+        /// <param name="candidates">The <see cref="CandidateSet"/>.</param>
+        /// <remarks>
+        /// Implementations of <see cref="IEndpointSelectorPolicy"/> should implement this method
+        /// and filter the set of candidates in the <paramref name="candidates"/> by setting
+        /// <see cref="CandidateState.IsValidCandidate"/> to <c>false</c> where desired.
+        /// </remarks>
         void Apply(HttpContext httpContext, CandidateSet candidates);
     }
 }

src/Microsoft.AspNetCore.Routing/Matching/MatcherEndpoint.cs

@@ -9,6 +9,9 @@ using Microsoft.AspNetCore.Routing.Patterns;
 
 namespace Microsoft.AspNetCore.Routing.Matching
 {
+    /// <summary>
+    /// Represents an <see cref="Endpoint"/> that can be used in URL matching or URL generation.
+    /// </summary>
     public sealed class MatcherEndpoint : Endpoint
     {
         internal static readonly Func<RequestDelegate, RequestDelegate> EmptyInvoker = (next) =>
@@ -16,6 +19,16 @@ namespace Microsoft.AspNetCore.Routing.Matching
             return (context) => Task.CompletedTask;
         };
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MatcherEndpoint"/> class.
+        /// </summary>
+        /// <param name="invoker">The delegate to invoke to create a <see cref="RequestDelegate"/>.</param>
+        /// <param name="routePattern">The <see cref="RoutePattern"/> to use in URL matching.</param>
+        /// <param name="order">The order assigned to the endpoint.</param>
+        /// <param name="metadata">
+        /// The <see cref="EndpointMetadataCollection"/> or metadata associated with the endpoint.
+        /// </param>
+        /// <param name="displayName">The informational display name of the endpoint.</param>
         public MatcherEndpoint(
             Func<RequestDelegate, RequestDelegate> invoker,
             RoutePattern routePattern,
@@ -39,10 +52,23 @@ namespace Microsoft.AspNetCore.Routing.Matching
             Order = order;
         }
 
+        /// <summary>
+        /// Gets the invoker. The invoker is a delegate used to create a <see cref="RequestDelegate"/>.
+        /// </summary>
         public Func<RequestDelegate, RequestDelegate> Invoker { get; }
 
+        /// <summary>
+        /// Gets the order value of endpoint.
+        /// </summary>
+        /// <remarks>
+        /// The order value provides absolute control over the priority
+        /// of an endpoint. Endpoints with a lower numeric value of order have higher priority.
+        /// </remarks>
         public int Order { get; }
         
+        /// <summary>
+        /// Gets the <see cref="RoutePattern"/> associated with the endpoint.
+        /// </summary>
         public RoutePattern RoutePattern { get; }
     }
 }

src/Microsoft.AspNetCore.Routing/Matching/MatcherPolicy.cs

@@ -1,10 +1,28 @@
 // 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 Microsoft.AspNetCore.Routing.Matching;
+
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Defines a policy that applies behaviors to the URL matcher. Implementations
+    /// of <see cref="MatcherPolicy"/> and related interfaces must be registered
+    /// in the dependency injection container as singleton services of type
+    /// <see cref="MatcherPolicy"/>.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="MatcherPolicy"/> implementations can implement the following
+    /// interfaces <see cref="IEndpointComparerPolicy"/>, <see cref="IEndpointSelectorPolicy"/>,
+    /// and <see cref="INodeBuilderPolicy"/>.
+    /// </remarks>
     public abstract class MatcherPolicy
     {
+        /// <summary>
+        /// Gets a value that determines the order the <see cref="MatcherPolicy"/> should
+        /// be applied. Policies are applied in ascending numeric value of the <see cref="Order"/>
+        /// property.
+        /// </summary>
         public abstract int Order { get; }
     }
 }