RouteValuesAddressMetadata ctors and XML docs (#818)

Author: JamesNK

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

@@ -29,7 +29,7 @@ public sealed class EndpointMetadataCollection : IReadOnlyList<object>
         private readonly ConcurrentDictionary<Type, object[]> _cache;
 
         /// <summary>
-        /// Creates a new <see cref="EndpointMetadataCollection"/>.
+        /// Creates a new instance of <see cref="EndpointMetadataCollection"/>.
         /// </summary>
         /// <param name="items">The metadata items.</param>
         public EndpointMetadataCollection(IEnumerable<object> items)
@@ -44,7 +44,7 @@ public EndpointMetadataCollection(IEnumerable<object> items)
         }
 
         /// <summary>
-        /// Creates a new <see cref="EndpointMetadataCollection"/>.
+        /// Creates a new instance of <see cref="EndpointMetadataCollection"/>.
         /// </summary>
         /// <param name="items">The metadata items.</param>
         public EndpointMetadataCollection(params object[] items)

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

@@ -14,7 +14,7 @@ public class RouteContext
         private RouteData _routeData;
 
         /// <summary>
-        /// Creates a new <see cref="RouteContext"/> for the provided <paramref name="httpContext"/>.
+        /// Creates a new instance of <see cref="RouteContext"/> for the provided <paramref name="httpContext"/>.
         /// </summary>
         /// <param name="httpContext">The <see cref="Http.HttpContext"/> associated with the current request.</param>
         public RouteContext(HttpContext httpContext)

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

@@ -16,15 +16,15 @@ public class RouteData
         private RouteValueDictionary _values;
 
         /// <summary>
-        /// Creates a new <see cref="RouteData"/> instance.
+        /// Creates a new instance of <see cref="RouteData"/> instance.
         /// </summary>
         public RouteData()
         {
             // Perf: Avoid allocating collections unless needed.
         }
 
         /// <summary>
-        /// Creates a new <see cref="RouteData"/> instance with values copied from <paramref name="other"/>.
+        /// Creates a new instance of <see cref="RouteData"/> instance with values copied from <paramref name="other"/>.
         /// </summary>
         /// <param name="other">The other <see cref="RouteData"/> instance to copy.</param>
         public RouteData(RouteData other)
@@ -52,7 +52,7 @@ public RouteData(RouteData other)
         }
 
         /// <summary>
-        /// Creates a new <see cref="RouteData"/> instance with the specified values.
+        /// Creates a new instance of <see cref="RouteData"/> instance with the specified values.
         /// </summary>
         /// <param name="values">The <see cref="RouteValueDictionary"/> values.</param>
         public RouteData(RouteValueDictionary values)
@@ -197,7 +197,7 @@ public struct RouteDataSnapshot
             private readonly RouteValueDictionary _values;
 
             /// <summary>
-            /// Creates a new <see cref="RouteDataSnapshot"/> for <paramref name="routeData"/>.
+            /// Creates a new instance of <see cref="RouteDataSnapshot"/> for <paramref name="routeData"/>.
             /// </summary>
             /// <param name="routeData">The <see cref="RouteData"/>.</param>
             /// <param name="dataTokens">The data tokens.</param>

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

@@ -25,7 +25,7 @@ public class RouteValueDictionary : IDictionary<string, object>, IReadOnlyDictio
         private int _count;
 
         /// <summary>
-        /// Creates a new <see cref="RouteValueDictionary"/> from the provided array.
+        /// Creates a new instance of <see cref="RouteValueDictionary"/> from the provided array.
         /// The new instance will take ownership of the array, and may mutate it.
         /// </summary>
         /// <param name="items">The items array.</param>

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

@@ -11,7 +11,7 @@ namespace Microsoft.AspNetCore.Routing
     public class VirtualPathContext
     {
         /// <summary>
-        /// Creates a new <see cref="VirtualPathContext"/>.
+        /// Creates a new instance of <see cref="VirtualPathContext"/>.
         /// </summary>
         /// <param name="httpContext">The <see cref="Http.HttpContext"/> associated with the current request.</param>
         /// <param name="ambientValues">The set of route values associated with the current request.</param>
@@ -25,7 +25,7 @@ public VirtualPathContext(
         }
 
         /// <summary>
-        /// Creates a new <see cref="VirtualPathContext"/>.
+        /// Creates a new instance of <see cref="VirtualPathContext"/>.
         /// </summary>
         /// <param name="httpContext">The <see cref="Http.HttpContext"/> associated with the current request.</param>
         /// <param name="ambientValues">The set of route values associated with the current request.</param>

src/Microsoft.AspNetCore.Routing/Constraints/HttpMethodRouteConstraint.cs

@@ -14,7 +14,7 @@ namespace Microsoft.AspNetCore.Routing.Constraints
     public class HttpMethodRouteConstraint : IRouteConstraint
     {
         /// <summary>
-        /// Creates a new <see cref="HttpMethodRouteConstraint"/> that accepts the HTTP methods specified
+        /// Creates a new instance of <see cref="HttpMethodRouteConstraint"/> that accepts the HTTP methods specified
         /// by <paramref name="allowedMethods"/>.
         /// </summary>
         /// <param name="allowedMethods">The allowed HTTP methods.</param>

src/Microsoft.AspNetCore.Routing/EndpointNameMetadata.cs

@@ -16,7 +16,7 @@ namespace Microsoft.AspNetCore.Routing
     public class EndpointNameMetadata : IEndpointNameMetadata
     {
         /// <summary>
-        /// Creates a new <see cref="EndpointNameMetadata"/> with the provided endpoint name.
+        /// Creates a new instance of <see cref="EndpointNameMetadata"/> with the provided endpoint name.
         /// </summary>
         /// <param name="endpointName">The endpoint name.</param>
         public EndpointNameMetadata(string endpointName)

src/Microsoft.AspNetCore.Routing/IRouteValuesAddressMetadata.cs

@@ -5,9 +5,20 @@
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents metadata used during link generation to find
+    /// the associated endpoint using route values.
+    /// </summary>
     public interface IRouteValuesAddressMetadata
     {
+        /// <summary>
+        /// Gets the route name. Can be null.
+        /// </summary>
         string RouteName { get; }
+
+        /// <summary>
+        /// Gets the required route values.
+        /// </summary>
         IReadOnlyDictionary<string, object> RequiredValues { get; }
     }
 }

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

@@ -19,7 +19,7 @@ private RoutePatternException(SerializationInfo info, StreamingContext context)
         }
 
         /// <summary>
-        /// Creates a new <see cref="RoutePatternException"/>.
+        /// Creates a new instance of <see cref="RoutePatternException"/>.
         /// </summary>
         /// <param name="pattern">The route pattern as raw text.</param>
         /// <param name="message">The exception message.</param>

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

@@ -67,7 +67,7 @@ public static RoutePattern Parse(string pattern, object defaults, object paramet
         }
 
         /// <summary>
-        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// Creates a new instance of <see cref="RoutePattern"/> from a collection of segments.
         /// </summary>
         /// <param name="segments">The collection of segments.</param>
         /// <returns>The <see cref="RoutePattern"/>.</returns>
@@ -82,7 +82,7 @@ public static RoutePattern Pattern(IEnumerable<RoutePatternPathSegment> segments
         }
 
         /// <summary>
-        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// Creates a new instance of <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>
@@ -158,7 +158,7 @@ public static RoutePattern Pattern(
         }
 
         /// <summary>
-        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// Creates a new instance of <see cref="RoutePattern"/> from a collection of segments.
         /// </summary>
         /// <param name="segments">The collection of segments.</param>
         /// <returns>The <see cref="RoutePattern"/>.</returns>
@@ -173,7 +173,7 @@ public static RoutePattern Pattern(params RoutePatternPathSegment[] segments)
         }
 
         /// <summary>
-        /// Creates a new <see cref="RoutePattern"/> from a collection of segments.
+        /// Creates a new instance of <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>

src/Microsoft.AspNetCore.Routing/RouteConstraintBuilder.cs

@@ -23,7 +23,7 @@ public class RouteConstraintBuilder
         private readonly Dictionary<string, List<IRouteConstraint>> _constraints;
         private readonly HashSet<string> _optionalParameters;
         /// <summary>
-        /// Creates a new <see cref="RouteConstraintBuilder"/> instance.
+        /// Creates a new instance of <see cref="RouteConstraintBuilder"/> instance.
         /// </summary>
         /// <param name="inlineConstraintResolver">The <see cref="IInlineConstraintResolver"/>.</param>
         /// <param name="displayName">The display name (for use in error messages).</param>

src/Microsoft.AspNetCore.Routing/RouteValuesAddressMetadata.cs

@@ -3,22 +3,61 @@
 
 using System;
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using System.Diagnostics;
 using System.Linq;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Metadata used during link generation to find the associated endpoint using route values.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString(),nq}")]
     public sealed class RouteValuesAddressMetadata : IRouteValuesAddressMetadata
     {
+        private static readonly IReadOnlyDictionary<string, object> EmptyRouteValues =
+            new ReadOnlyDictionary<string, object>(new Dictionary<string, object>());
+
+        /// <summary>
+        /// Creates a new instance of <see cref="RouteValuesAddressMetadata"/> with the provided route name.
+        /// </summary>
+        /// <param name="routeName">The route name. Can be null.</param>
+        public RouteValuesAddressMetadata(string routeName) : this(routeName, EmptyRouteValues)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new instance of <see cref="RouteValuesAddressMetadata"/> with the provided required route values.
+        /// </summary>
+        /// <param name="requiredValues">The required route values.</param>
+        public RouteValuesAddressMetadata(IReadOnlyDictionary<string, object> requiredValues) : this(null, requiredValues)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new instance of <see cref="RouteValuesAddressMetadata"/> with the provided route name and required route values.
+        /// </summary>
+        /// <param name="routeName">The route name. Can be null.</param>
+        /// <param name="requiredValues">The required route values.</param>
         public RouteValuesAddressMetadata(string routeName, IReadOnlyDictionary<string, object> requiredValues)
         {
+            if (requiredValues == null)
+            {
+                throw new ArgumentNullException(nameof(requiredValues));
+            }
+
             RouteName = routeName;
             RequiredValues = requiredValues;
         }
 
+        /// <summary>
+        /// Gets the route name. Can be null.
+        /// </summary>
         public string RouteName { get; }
 
+        /// <summary>
+        /// Gets the required route values.
+        /// </summary>
         public IReadOnlyDictionary<string, object> RequiredValues { get; }
 
         internal string DebuggerToString()

src/Microsoft.AspNetCore.Routing/Template/InlineConstraint.cs

@@ -12,7 +12,7 @@ namespace Microsoft.AspNetCore.Routing.Template
     public class InlineConstraint
     {
         /// <summary>
-        /// Creates a new <see cref="InlineConstraint"/>.
+        /// Creates a new instance of <see cref="InlineConstraint"/>.
         /// </summary>
         /// <param name="constraint">The constraint text.</param>
         public InlineConstraint(string constraint)

src/Microsoft.AspNetCore.Routing/Tree/TreeRouter.cs

@@ -30,7 +30,7 @@ public class TreeRouter : IRouter
         private readonly ILogger _constraintLogger;
 
         /// <summary>
-        /// Creates a new <see cref="TreeRouter"/>.
+        /// Creates a new instance of <see cref="TreeRouter"/>.
         /// </summary>
         /// <param name="trees">The list of <see cref="UrlMatchingTree"/> that contains the route entries.</param>
         /// <param name="linkGenerationEntries">The set of <see cref="OutboundRouteEntry"/>.</param>

test/Microsoft.AspNetCore.Routing.Tests/EndpointFactory.cs

@@ -22,7 +22,7 @@ public static RouteEndpoint CreateRouteEndpoint(
             var d = new List<object>(metadata ?? Array.Empty<object>());
             if (requiredValues != null)
             {
-                d.Add(new RouteValuesAddressMetadata(null, new RouteValueDictionary(requiredValues)));
+                d.Add(new RouteValuesAddressMetadata(new RouteValueDictionary(requiredValues)));
             }
 
             return new RouteEndpoint(