Add docs - EndpointFeature and related types (#687)

* Add docs - EndpointFeature and related types

* Add docs for route patterns

src/Microsoft.AspNetCore.Routing.Abstractions/Endpoint.cs

@@ -1,13 +1,22 @@
 // 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.Diagnostics;
-
 namespace Microsoft.AspNetCore.Routing
 {
-    [DebuggerDisplay("{DisplayName,nq}")]
+    /// <summary>
+    /// Respresents a logical endpoint in an application.
+    /// </summary>
     public abstract class Endpoint
     {
+        /// <summary>
+        /// Creates a new instance of <see cref="Endpoint"/>.
+        /// </summary>
+        /// <param name="metadata">
+        /// The endpoint <see cref="EndpointMetadataCollection"/>. May be null.
+        /// </param>
+        /// <param name="displayName">
+        /// The informational display name of the endpoint. May be null.
+        /// </param>
         protected Endpoint(
             EndpointMetadataCollection metadata,
             string displayName)
@@ -17,8 +26,16 @@ namespace Microsoft.AspNetCore.Routing
             DisplayName = displayName;
         }
 
+        /// <summary>
+        /// Gets the informational display name of this endpoint.
+        /// </summary>
         public string DisplayName { get; }
 
+        /// <summary>
+        /// Gets the collection of metadata associated with this endpoint.
+        /// </summary>
         public EndpointMetadataCollection Metadata { get; }
+
+        public override string ToString() => DisplayName ?? base.ToString();
     }
 }

src/Microsoft.AspNetCore.Routing.Abstractions/EndpointMetadataCollection.cs

@@ -8,12 +8,27 @@ using System.Linq;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// A collection of arbitrary metadata associated with an endpoint.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="EndpointMetadataCollection"/> instances contain a list of metadata items
+    /// of arbitrary types. The metadata items are stored as an ordered collection with
+    /// items arranged in ascending order of precedence.
+    /// </remarks>
     public sealed class EndpointMetadataCollection : IReadOnlyList<object>
     {
+        /// <summary>
+        /// An empty <see cref="EndpointMetadataCollection"/>.
+        /// </summary>
         public static readonly EndpointMetadataCollection Empty = new EndpointMetadataCollection(Array.Empty<object>());
 
         private readonly object[] _items;
 
+        /// <summary>
+        /// Creates a new <see cref="EndpointMetadataCollection"/>.
+        /// </summary>
+        /// <param name="items">The metadata items.</param>
         public EndpointMetadataCollection(IEnumerable<object> items)
         {
             if (items == null)
@@ -24,15 +39,34 @@ namespace Microsoft.AspNetCore.Routing
             _items = items.ToArray();
         }
 
+        /// <summary>
+        /// Creates a new <see cref="EndpointMetadataCollection"/>.
+        /// </summary>
+        /// <param name="items">The metadata items.</param>
         public EndpointMetadataCollection(params object[] items)
             : this((IEnumerable<object>)items)
         {
         }
 
+        /// <summary>
+        /// Gets the item at <paramref name="index"/>.
+        /// </summary>
+        /// <param name="index">The index of the item to retrieve.</param>
+        /// <returns>The item at <paramref name="index"/>.</returns>
         public object this[int index] => _items[index];
 
+        /// <summary>
+        /// Gets the count of metadata items.
+        /// </summary>
         public int Count => _items.Length;
 
+        /// <summary>
+        /// Gets the most significant metadata item of type <typeparamref name="T"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of metadata to retrieve.</typeparam>
+        /// <returns>
+        /// The most significant metadata of type <typeparamref name="T"/> or <c>null</c>.
+        /// </returns>
         public T GetMetadata<T>() where T : class
         {
             for (var i = _items.Length - 1; i >= 0; i--)
@@ -47,6 +81,12 @@ namespace Microsoft.AspNetCore.Routing
             return default;
         }
 
+        /// <summary>
+        /// Gets the metadata items of type <typeparamref name="T"/> in ascending
+        /// order of precedence.
+        /// </summary>
+        /// <typeparam name="T">The type of metadata.</typeparam>
+        /// <returns>A sequence of metadata items of <typeparamref name="T"/>.</returns>
         public IEnumerable<T> GetOrderedMetadata<T>() where T : class
         {
             for (var i = 0; i < _items.Length; i++)
@@ -59,12 +99,27 @@ namespace Microsoft.AspNetCore.Routing
             }
         }
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator"/> of all metadata items.
+        /// </summary>
+        /// <returns>An <see cref="IEnumerator"/> of all metadata items.</returns>
         public Enumerator GetEnumerator() => new Enumerator(this);
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{Object}"/> of all metadata items.
+        /// </summary>
+        /// <returns>An <see cref="IEnumerator{Object}"/> of all metadata items.</returns>
         IEnumerator<object> IEnumerable<object>.GetEnumerator() => GetEnumerator();
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator"/> of all metadata items.
+        /// </summary>
+        /// <returns>An <see cref="IEnumerator"/> of all metadata items.</returns>
         IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+        /// <summary>
+        /// Enumerates the elements of an <see cref="EndpointMetadataCollection"/>.
+        /// </summary>
         public struct Enumerator : IEnumerator<object>
         {
             // Intentionally not readonly to prevent defensive struct copies
@@ -79,12 +134,25 @@ namespace Microsoft.AspNetCore.Routing
                 _current = null;
             }
 
+            /// <summary>
+            /// Gets the element at the current position of the enumerator
+            /// </summary>
             public object Current => _current;
 
+            /// <summary>
+            /// Releases all resources used by the <see cref="Enumerator"/>.
+            /// </summary>
             public void Dispose()
             {
             }
 
+            /// <summary>
+            /// Advances the enumerator to the next element of the <see cref="Enumerator"/>.
+            /// </summary>
+            /// <returns>
+            /// <c>true</c> if the enumerator was successfully advanced to the next element;
+            /// <c>false</c> if the enumerator has passed the end of the collection.
+            /// </returns>
             public bool MoveNext()
             {
                 if (_index < _items.Length)
@@ -97,6 +165,9 @@ namespace Microsoft.AspNetCore.Routing
                 return false;
             }
 
+            /// <summary>
+            /// Sets the enumerator to its initial position, which is before the first element in the collection.
+            /// </summary>
             public void Reset()
             {
                 _index = 0;

src/Microsoft.AspNetCore.Routing.Abstractions/IEndpointFeature.cs

@@ -6,12 +6,28 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// A feature interface for endpoint routing. Use <see cref="HttpContext.Features"/>
+    /// to access an instance associated with the current request.
+    /// </summary>
     public interface IEndpointFeature
     {
+        /// <summary>
+        /// Gets or sets the selected <see cref="Routing.Endpoint"/> for the current
+        /// request.
+        /// </summary>
         Endpoint Endpoint { get; set; }
 
+        /// <summary>
+        /// Gets or sets a delegate that can be used to invoke the current
+        /// <see cref="Routing.Endpoint"/>.
+        /// </summary>
         Func<RequestDelegate, RequestDelegate> Invoker { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="RouteValueDictionary"/> associated with the currrent
+        /// request.
+        /// </summary>
         RouteValueDictionary Values { get; set; }
     }
 }

src/Microsoft.AspNetCore.Routing/EndpointFeature.cs

@@ -6,15 +6,30 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// A default implementation of <see cref="IEndpointFeature"/> and <see cref="IRoutingFeature"/>.
+    /// </summary>
     public sealed class EndpointFeature : IEndpointFeature, IRoutingFeature
     {
         private RouteData _routeData;
         private RouteValueDictionary _values;
 
+        /// <summary>
+        /// Gets or sets the selected <see cref="Routing.Endpoint"/> for the current
+        /// request.
+        /// </summary>
         public Endpoint Endpoint { get; set; }
 
+        /// <summary>
+        /// Gets or sets a delegate that can be used to invoke the current
+        /// <see cref="Routing.Endpoint"/>.
+        /// </summary>
         public Func<RequestDelegate, RequestDelegate> Invoker { get; set; }
 
+        /// <summary>
+        /// Gets or sets the <see cref="RouteValueDictionary"/> associated with the currrent
+        /// request.
+        /// </summary>
         public RouteValueDictionary Values
         {
             get => _values;
@@ -27,6 +42,12 @@ namespace Microsoft.AspNetCore.Routing
             }
         }
 
+        /// <summary>
+        /// Gets or sets the <see cref="RouteData"/> for the current request.
+        /// </summary>
+        /// <remarks>
+        /// The setter is not implemented. Use <see cref="Values"/> to set the route values.
+        /// </remarks>
         RouteData IRoutingFeature.RouteData
         {
             get

src/Microsoft.AspNetCore.Routing/Patterns/RoutePattern.cs

@@ -9,6 +9,11 @@ using Microsoft.AspNetCore.Routing.Template;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Represents a parsed route template with default values and constraints.
+    /// Use <see cref="RoutePatternFactory"/> to create <see cref="RoutePattern"/>
+    /// instances. Instances of <see cref="RoutePattern"/> are immutable.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePattern
     {
@@ -36,18 +41,49 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             OutboundPrecedence = RoutePrecedence.ComputeOutbound(this);
         }
 
+        /// <summary>
+        /// Gets the set of default values for the route pattern.
+        /// The keys of <see cref="Defaults"/> are the route parameter names.
+        /// </summary>
         public IReadOnlyDictionary<string, object> Defaults { get; }
 
+        /// <summary>
+        /// Gets the set of constraint references for the route pattern.
+        /// The keys of <see cref="Constraints"/> are the route parameter names.
+        /// </summary>
         public IReadOnlyDictionary<string, IReadOnlyList<RoutePatternConstraintReference>> Constraints { get; }
 
+        /// <summary>
+        /// Gets the precedence value of the route pattern for URL matching.
+        /// </summary>
+        /// <remarks>
+        /// Precedence is a computed value based on the structure of the route pattern
+        /// used for building URL matching data structures.
+        /// </remarks>
         public decimal InboundPrecedence { get; }
 
+        /// <summary>
+        /// Gets the precedence value of the route pattern for URL generation.
+        /// </summary>
+        /// <remarks>
+        /// Precedence is a computed value based on the structure of the route pattern
+        /// used for building URL generation data structures.
+        /// </remarks>
         public decimal OutboundPrecedence { get; }
 
+        /// <summary>
+        /// Gets the raw text supplied when parsing the route pattern. May be null.
+        /// </summary>
         public string RawText { get; }
 
+        /// <summary>
+        /// Gets the list of route parameters.
+        /// </summary>
         public IReadOnlyList<RoutePatternParameterPart> Parameters { get; }
 
+        /// <summary>
+        /// Gets the list of path segments.
+        /// </summary>
         public IReadOnlyList<RoutePatternPathSegment> PathSegments { get; }
 
         /// <summary>

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternConstraintReference.cs

@@ -7,7 +7,8 @@ using Microsoft.AspNetCore.Routing.Matching;
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
     /// <summary>
-    /// The parsed representation of a constraint in a <see cref="RoutePattern"/> parameter.
+    /// The parsed representation of a constraint in a <see cref="RoutePattern"/> parameter. Instances
+    /// of <see cref="RoutePatternConstraintReference"/> are immutable.
     /// </summary>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePatternConstraintReference

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternException.cs

@@ -6,6 +6,9 @@ using System.Runtime.Serialization;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// An exception that is thrown for error constructing a <see cref="RoutePattern"/>.
+    /// </summary>
     [Serializable]
     public sealed class RoutePatternException : Exception
     {
@@ -15,6 +18,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Pattern = (string)info.GetValue(nameof(Pattern), typeof(string));
         }
 
+        /// <summary>
+        /// Creates a new <see cref="RoutePatternException"/>.
+        /// </summary>
+        /// <param name="pattern">The route pattern as raw text.</param>
+        /// <param name="message">The exception message.</param>
         public RoutePatternException(string pattern, string message)
             : base(message)
         {
@@ -31,8 +39,16 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Pattern = pattern;
         }
 
+        /// <summary>
+        /// Gets the route pattern associated with this exception.
+        /// </summary>
         public string Pattern { get; }
 
+        /// <summary>
+        /// Populates a <see cref="SerializationInfo"/> with the data needed to serialize the target object.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> to populate with data.</param>
+        /// <param name="context">The destination (<see cref="StreamingContext" />) for this serialization.</param>
         public override void GetObjectData(SerializationInfo info, StreamingContext context)
         {
             info.AddValue(nameof(Pattern), Pattern);

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternFactory.cs

@@ -9,8 +9,18 @@ using Microsoft.AspNetCore.Routing.Matching;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Contains factory methods for creating <see cref="RoutePattern"/> and related types.
+    /// Use <see cref="Parse(string)"/> to parse a route pattern in
+    /// string format.
+    /// </summary>
     public static class RoutePatternFactory
     {
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from its string representation.
+        /// </summary>
+        /// <param name="pattern">The route pattern string to parse.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Parse(string pattern)
         {
             if (pattern == null)
@@ -21,6 +31,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return RoutePatternParser.Parse(pattern);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from its string representation along
+        /// with provided default values and constraints.
+        /// </summary>
+        /// <param name="pattern">The route pattern string to parse.</param>
+        /// <param name="defaults">
+        /// Additional default values to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the parsed route pattern.
+        /// </param>
+        /// <param name="constraints">
+        /// Additional constraints to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the parsed route pattern.
+        /// </param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Parse(string pattern, object defaults, object constraints)
         {
             if (pattern == null)
@@ -32,6 +58,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return Pattern(original.RawText, defaults, constraints, original.PathSegments);
         }
 
+        /// <summary>
+        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// </summary>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(IEnumerable<RoutePatternPathSegment> segments)
         {
             if (segments == null)
@@ -42,6 +73,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(null, null, null, segments);
         }
 
+        /// <summary>
+        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// </summary>
+        /// <param name="rawText">The raw text to associate with the route pattern. May be null.</param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(string rawText, IEnumerable<RoutePatternPathSegment> segments)
         {
             if (segments == null)
@@ -52,6 +89,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(rawText, null, null, segments);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from a collection of segments along
+        /// with provided default values and constraints.
+        /// </summary>
+        /// <param name="defaults">
+        /// Additional default values to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="constraints">
+        /// Additional constraints to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(
             object defaults,
             object constraints,
@@ -65,6 +118,23 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(null, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from a collection of segments along
+        /// with provided default values and constraints.
+        /// </summary>
+        /// <param name="rawText">The raw text to associate with the route pattern.</param>
+        /// <param name="defaults">
+        /// Additional default values to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="constraints">
+        /// Additional constraints to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(
             string rawText,
             object defaults,
@@ -79,6 +149,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(rawText, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments);
         }
 
+        /// <summary>
+        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// </summary>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(params RoutePatternPathSegment[] segments)
         {
             if (segments == null)
@@ -89,6 +164,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(null, null, null, segments);
         }
 
+        /// <summary>
+        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// </summary>
+        /// <param name="rawText">The raw text to associate with the route pattern. May be null.</param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(string rawText, params RoutePatternPathSegment[] segments)
         {
             if (segments == null)
@@ -99,6 +180,22 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(rawText, null, null, segments);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from a collection of segments along
+        /// with provided default values and constraints.
+        /// </summary>
+        /// <param name="defaults">
+        /// Additional default values to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="constraints">
+        /// Additional constraints to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(
             object defaults,
             object constraints,
@@ -112,6 +209,23 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return PatternCore(null, new RouteValueDictionary(defaults), new RouteValueDictionary(constraints), segments);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePattern"/> from a collection of segments along
+        /// with provided default values and constraints.
+        /// </summary>
+        /// <param name="rawText">The raw text to associate with the route pattern.</param>
+        /// <param name="defaults">
+        /// Additional default values to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="constraints">
+        /// Additional constraints to associated with the route pattern. May be null.
+        /// The provided object will be converted to key-value pairs using <see cref="RouteValueDictionary"/>
+        /// and then merged into the route pattern.
+        /// </param>
+        /// <param name="segments">The collection of segments.</param>
+        /// <returns>The <see cref="RoutePattern"/>.</returns>
         public static RoutePattern Pattern(
             string rawText,
             object defaults,
@@ -251,6 +365,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             }
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternPathSegment"/> from the provided collection
+        /// of parts.
+        /// </summary>
+        /// <param name="parts">The collection of parts.</param>
+        /// <returns>The <see cref="RoutePatternPathSegment"/>.</returns>
         public static RoutePatternPathSegment Segment(IEnumerable<RoutePatternPart> parts)
         {
             if (parts == null)
@@ -261,6 +381,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return SegmentCore(parts);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternPathSegment"/> from the provided collection
+        /// of parts.
+        /// </summary>
+        /// <param name="parts">The collection of parts.</param>
+        /// <returns>The <see cref="RoutePatternPathSegment"/>.</returns>
         public static RoutePatternPathSegment Segment(params RoutePatternPart[] parts)
         {
             if (parts == null)
@@ -276,6 +402,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return new RoutePatternPathSegment(parts.ToArray());
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternLiteralPart"/> from the provided text
+        /// content.
+        /// </summary>
+        /// <param name="content">The text content.</param>
+        /// <returns>The <see cref="RoutePatternLiteralPart"/>.</returns>
         public static RoutePatternLiteralPart LiteralPart(string content)
         {
             if (string.IsNullOrEmpty(content))
@@ -296,6 +428,12 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return new RoutePatternLiteralPart(content);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternSeparatorPart"/> from the provided text
+        /// content.
+        /// </summary>
+        /// <param name="content">The text content.</param>
+        /// <returns>The <see cref="RoutePatternSeparatorPart"/>.</returns>
         public static RoutePatternSeparatorPart SeparatorPart(string content)
         {
             if (string.IsNullOrEmpty(content))
@@ -311,6 +449,11 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return new RoutePatternSeparatorPart(content);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternParameterPart"/> from the provided parameter name.
+        /// </summary>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <returns>The <see cref="RoutePatternParameterPart"/>.</returns>
         public static RoutePatternParameterPart ParameterPart(string parameterName)
         {
             if (string.IsNullOrEmpty(parameterName))
@@ -330,6 +473,13 @@ namespace Microsoft.AspNetCore.Routing.Patterns
                 constraints: Array.Empty<RoutePatternConstraintReference>());
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternParameterPart"/> from the provided parameter name
+        /// and default value.
+        /// </summary>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="default">The parameter default value. May be <c>null</c>.</param>
+        /// <returns>The <see cref="RoutePatternParameterPart"/>.</returns>
         public static RoutePatternParameterPart ParameterPart(string parameterName, object @default)
         {
             if (string.IsNullOrEmpty(parameterName))
@@ -349,6 +499,14 @@ namespace Microsoft.AspNetCore.Routing.Patterns
                 constraints: Array.Empty<RoutePatternConstraintReference>());
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternParameterPart"/> from the provided parameter name
+        /// and default value, and parameter kind.
+        /// </summary>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="default">The parameter default value. May be <c>null</c>.</param>
+        /// <param name="parameterKind">The parameter kind.</param>
+        /// <returns>The <see cref="RoutePatternParameterPart"/>.</returns>
         public static RoutePatternParameterPart ParameterPart(
             string parameterName,
             object @default,
@@ -376,6 +534,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns
                 constraints: Array.Empty<RoutePatternConstraintReference>());
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternParameterPart"/> from the provided parameter name
+        /// and default value, parameter kind, and constraints.
+        /// </summary>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="default">The parameter default value. May be <c>null</c>.</param>
+        /// <param name="parameterKind">The parameter kind.</param>
+        /// <param name="constraints">The constraints to associated with the parameter.</param>
+        /// <returns>The <see cref="RoutePatternParameterPart"/>.</returns>
         public static RoutePatternParameterPart ParameterPart(
             string parameterName,
             object @default,
@@ -409,6 +576,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns
                 constraints: constraints);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternParameterPart"/> from the provided parameter name
+        /// and default value, parameter kind, and constraints.
+        /// </summary>
+        /// <param name="parameterName">The parameter name.</param>
+        /// <param name="default">The parameter default value. May be <c>null</c>.</param>
+        /// <param name="parameterKind">The parameter kind.</param>
+        /// <param name="constraints">The constraints to associated with the parameter.</param>
+        /// <returns>The <see cref="RoutePatternParameterPart"/>.</returns>
         public static RoutePatternParameterPart ParameterPart(
             string parameterName,
             object @default,
@@ -451,6 +627,16 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return new RoutePatternParameterPart(parameterName, @default, parameterKind, constraints.ToArray());
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternConstraintReference"/> from the provided object.
+        /// </summary>
+        /// <param name="constraint">
+        /// The constraint object, which must be of type <see cref="IRouteConstraint"/>,
+        /// <see cref="MatcherPolicy"/>, or <see cref="String"/>. If the constraint object
+        /// is a <see cref="String"/> it will be tranformed into an instance of 
+        /// <see cref="RegexRouteConstraint"/>.
+        /// </param>
+        /// <returns>The <see cref="RoutePatternConstraintReference"/>.</returns>
         public static RoutePatternConstraintReference Constraint(object constraint)
         {
             // Similar to RouteConstraintBuilder
@@ -475,6 +661,13 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             }
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternConstraintReference"/> from the provided object.
+        /// </summary>
+        /// <param name="constraint">
+        /// The constraint object.
+        /// </param>
+        /// <returns>The <see cref="RoutePatternConstraintReference"/>.</returns>
         public static RoutePatternConstraintReference Constraint(IRouteConstraint constraint)
         {
             if (constraint == null)
@@ -485,6 +678,13 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return ConstraintCore(constraint);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternConstraintReference"/> from the provided object.
+        /// </summary>
+        /// <param name="matchProcessor">
+        /// The match processor object.
+        /// </param>
+        /// <returns>The <see cref="RoutePatternConstraintReference"/>.</returns>
         public static RoutePatternConstraintReference Constraint(MatchProcessor matchProcessor)
         {
             if (matchProcessor == null)
@@ -495,6 +695,14 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             return ConstraintCore(matchProcessor);
         }
 
+        /// <summary>
+        /// Creates a <see cref="RoutePatternConstraintReference"/> from the provided object.
+        /// </summary>
+        /// <param name="constraint">
+        /// The constraint text, which will be tranformed into an instance of 
+        /// <see cref="RegexRouteConstraint"/>.
+        /// </param>
+        /// <returns>The <see cref="RoutePatternConstraintReference"/>.</returns>
         public static RoutePatternConstraintReference Constraint(string constraint)
         {
             if (string.IsNullOrEmpty(constraint))

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternLiteralPart.cs

@@ -5,6 +5,10 @@ using System.Diagnostics;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Resprents a literal text part of a route pattern. Instances of <see cref="RoutePatternLiteralPart"/>
+    /// are immutable.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePatternLiteralPart : RoutePatternPart
     {
@@ -15,6 +19,9 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Content = content;
         }
 
+        /// <summary>
+        /// Gets the text content.
+        /// </summary>
         public string Content { get; }
 
         internal override string DebuggerToString()

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternMatcher.cs

@@ -2,11 +2,10 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
-using System.Collections.Generic;
 using System.Diagnostics;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing.Internal;
 using Microsoft.AspNetCore.Routing.Patterns;
-using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Routing

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterKind.cs

@@ -3,10 +3,25 @@
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Defines the kinds of <see cref="RoutePatternParameterPart"/> instances.
+    /// </summary>
     public enum RoutePatternParameterKind
     {
+        /// <summary>
+        /// The <see cref="RoutePatternParameterKind"/> of a standard parameter
+        /// without optional or catch all behavior.
+        /// </summary>
         Standard,
+
+        /// <summary>
+        /// The <see cref="RoutePatternParameterKind"/> of an optional parameter.
+        /// </summary>
         Optional,
+
+        /// <summary>
+        /// The <see cref="RoutePatternParameterKind"/> of a catch-all parameter.
+        /// </summary>
         CatchAll,
     }
 }

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternParameterPart.cs

@@ -7,6 +7,10 @@ using System.Text;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Represents a parameter part in a route pattern. Instances of <see cref="RoutePatternParameterPart"/>
+    /// are immutable.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePatternParameterPart : RoutePatternPart
     {
@@ -25,16 +29,36 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Constraints = constraints;
         }
 
+        /// <summary>
+        /// Gets the list of constraints associated with this parameter.
+        /// </summary>
         public IReadOnlyList<RoutePatternConstraintReference> Constraints { get; }
 
+        /// <summary>
+        /// Gets the default value of this route parameter. May be null.
+        /// </summary>
         public object Default { get; }
 
+        /// <summary>
+        /// Returns <c>true</c> if this part is a catch-all parameter.
+        /// Otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsCatchAll => ParameterKind == RoutePatternParameterKind.CatchAll;
 
+        /// <summary>
+        /// Returns <c>true</c> if this part is an optional parameter.
+        /// Otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsOptional => ParameterKind == RoutePatternParameterKind.Optional;
 
+        /// <summary>
+        /// Gets the <see cref="RoutePatternParameterKind"/> of this parameter.
+        /// </summary>
         public RoutePatternParameterKind ParameterKind { get; }
 
+        /// <summary>
+        /// Gets the parameter name.
+        /// </summary>
         public string Name { get; }
 
         internal override string DebuggerToString()

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPart.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Represents a part of a route pattern.
+    /// </summary>
     public abstract class RoutePatternPart
     {
         // This class is **not** an extensibility point - every part of the routing system
@@ -14,12 +17,24 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             PartKind = partKind;
         }
 
+        /// <summary>
+        /// Gets the <see cref="RoutePatternPartKind"/> of this part.
+        /// </summary>
         public RoutePatternPartKind PartKind { get; }
 
+        /// <summary>
+        /// Returns <c>true</c> if this part is literal text. Otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsLiteral => PartKind == RoutePatternPartKind.Literal;
 
+        /// <summary>
+        /// Returns <c>true</c> if this part is a route parameter. Otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsParameter => PartKind == RoutePatternPartKind.Parameter;
 
+        /// <summary>
+        /// Returns <c>true</c> if this part is an optional separator. Otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsSeparator => PartKind == RoutePatternPartKind.Separator;
 
         internal abstract string DebuggerToString();

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPartKind.cs

@@ -3,10 +3,24 @@
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Defines the kinds of <see cref="RoutePatternPart"/> instances.
+    /// </summary>
     public enum RoutePatternPartKind
     {
+        /// <summary>
+        /// The <see cref="RoutePatternPartKind"/> of a <see cref="RoutePatternLiteralPart"/>.
+        /// </summary>
         Literal,
+
+        /// <summary>
+        /// The <see cref="RoutePatternPartKind"/> of a <see cref="RoutePatternParameterPart"/>.
+        /// </summary>
         Parameter,
+
+        /// <summary>
+        /// The <see cref="RoutePatternPartKind"/> of a <see cref="RoutePatternSeparatorPart"/>.
+        /// </summary>
         Separator,
     }
 }

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternPathSegment.cs

@@ -7,6 +7,16 @@ using System.Linq;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Represents a path segment in a route pattern. Instances of <see cref="RoutePatternPathSegment"/> are
+    /// immutable.
+    /// </summary>
+    /// <remarks>
+    /// Route patterns are made up of URL path segments, delimited by <c>/</c>. A
+    /// <see cref="RoutePatternPathSegment"/> contains a group of 
+    /// <see cref="RoutePatternPart"/> that represent the structure of a segment
+    /// in a route pattern.
+    /// </remarks>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePatternPathSegment
     {
@@ -15,8 +25,15 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Parts = parts;
         }
 
+        /// <summary>
+        /// Returns <c>true</c> if the segment contains a single part;
+        /// otherwise returns <c>false</c>.
+        /// </summary>
         public bool IsSimple => Parts.Count == 1;
 
+        /// <summary>
+        /// Gets the list of parts in this segment.
+        /// </summary>
         public IReadOnlyList<RoutePatternPart> Parts { get; }
 
         internal string DebuggerToString()

src/Microsoft.AspNetCore.Routing/Patterns/RoutePatternSeparatorPart.cs

@@ -5,6 +5,27 @@ using System.Diagnostics;
 
 namespace Microsoft.AspNetCore.Routing.Patterns
 {
+    /// <summary>
+    /// Represents an optional separator part of a route pattern. Instances of <see cref="RoutePatternSeparatorPart"/>
+    /// are immutable.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// An optional separator is a literal text delimiter that appears between
+    /// two parameter parts in the last segment of a route pattern. The only separator
+    /// that is recognized is <c>.</c>.
+    /// </para>
+    /// <para>
+    /// <example>
+    /// In the route pattern <c>/{controller}/{action}/{id?}.{extension?}</c>
+    /// the <c>.</c> character is an optional separator.
+    /// </example>
+    /// </para>
+    /// <para>
+    /// An optional separator character does not need to present in the URL path
+    /// of a request for the route pattern to match.
+    /// </para>
+    /// </remarks>
     [DebuggerDisplay("{DebuggerToString()}")]
     public sealed class RoutePatternSeparatorPart : RoutePatternPart
     {
@@ -16,6 +37,9 @@ namespace Microsoft.AspNetCore.Routing.Patterns
             Content = content;
         }
 
+        /// <summary>
+        /// Gets the text content of the part.
+        /// </summary>
         public string Content { get; }
 
         internal override string DebuggerToString()