Add XML docs to data sources and metadata (#692)

src/Microsoft.AspNetCore.Routing/CompositeEndpointDataSource.cs

@@ -12,6 +12,9 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents an <see cref="EndpointDataSource"/> whose values come from a collection of <see cref="EndpointDataSource"/> instances.
+    /// </summary>
     [DebuggerDisplay("{DebuggerDisplayString,nq}")]
     public sealed class CompositeEndpointDataSource : EndpointDataSource
     {
@@ -33,12 +36,20 @@ namespace Microsoft.AspNetCore.Routing
             _lock = new object();
         }
 
+        /// <summary>
+        /// Gets a <see cref="IChangeToken"/> used to signal invalidation of cached <see cref="Endpoint"/>
+        /// instances.
+        /// </summary>
+        /// <returns>The <see cref="IChangeToken"/>.</returns>
         public override IChangeToken GetChangeToken()
         {
             EnsureInitialized();
             return _consumerChangeToken;
         }
 
+        /// <summary>
+        /// Returns a read-only collection of <see cref="Endpoint"/> instances.
+        /// </summary>
         public override IReadOnlyList<Endpoint> Endpoints
         {
             get

src/Microsoft.AspNetCore.Routing/DefaultEndpointDataSource.cs

@@ -8,15 +8,26 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Provides a collection of <see cref="Endpoint"/> instances.
+    /// </summary>
     public sealed class DefaultEndpointDataSource : EndpointDataSource
     {
         private readonly List<Endpoint> _endpoints;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DefaultEndpointDataSource" /> class.
+        /// </summary>
+        /// <param name="endpoints">The <see cref="Endpoint"/> instances that the data source will return.</param>
         public DefaultEndpointDataSource(params Endpoint[] endpoints)
             : this((IEnumerable<Endpoint>) endpoints)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DefaultEndpointDataSource" /> class.
+        /// </summary>
+        /// <param name="endpoints">The <see cref="Endpoint"/> instances that the data source will return.</param>
         public DefaultEndpointDataSource(IEnumerable<Endpoint> endpoints)
         {
             if (endpoints == null)
@@ -28,8 +39,16 @@ namespace Microsoft.AspNetCore.Routing
             _endpoints.AddRange(endpoints);
         }
 
+        /// <summary>
+        /// Gets a <see cref="IChangeToken"/> used to signal invalidation of cached <see cref="Endpoint"/>
+        /// instances.
+        /// </summary>
+        /// <returns>The <see cref="IChangeToken"/>.</returns>
         public override IChangeToken GetChangeToken() => NullChangeToken.Singleton;
 
+        /// <summary>
+        /// Returns a read-only collection of <see cref="Endpoint"/> instances.
+        /// </summary>
         public override IReadOnlyList<Endpoint> Endpoints => _endpoints;
     }
 }

src/Microsoft.AspNetCore.Routing/EndpointDataSource.cs

@@ -6,10 +6,21 @@ using Microsoft.Extensions.Primitives;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Provides a collection of <see cref="Endpoint"/> instances.
+    /// </summary>
     public abstract class EndpointDataSource
     {
+        /// <summary>
+        /// Gets a <see cref="IChangeToken"/> used to signal invalidation of cached <see cref="Endpoint"/>
+        /// instances.
+        /// </summary>
+        /// <returns>The <see cref="IChangeToken"/>.</returns>
         public abstract IChangeToken GetChangeToken();
 
+        /// <summary>
+        /// Returns a read-only collection of <see cref="Endpoint"/> instances.
+        /// </summary>
         public abstract IReadOnlyList<Endpoint> Endpoints { get; }
     }
 }

src/Microsoft.AspNetCore.Routing/HttpMethodMetadata.cs

@@ -8,14 +8,32 @@ using System.Linq;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents HTTP method metadata used during routing.
+    /// </summary>
     [DebuggerDisplay("{DebuggerToString(),nq}")]
     public sealed class HttpMethodMetadata : IHttpMethodMetadata
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HttpMethodMetadata" /> class.
+        /// </summary>
+        /// <param name="httpMethods">
+        /// The HTTP methods used during routing.
+        /// An empty collection means any HTTP method will be accepted.
+        /// </param>
         public HttpMethodMetadata(IEnumerable<string> httpMethods)
             : this(httpMethods, acceptCorsPreflight: false)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HttpMethodMetadata" /> class.
+        /// </summary>
+        /// <param name="httpMethods">
+        /// The HTTP methods used during routing.
+        /// An empty collection means any HTTP method will be accepted.
+        /// </param>
+        /// <param name="acceptCorsPreflight">A value indicating whether routing accepts CORS preflight requests.</param>
         public HttpMethodMetadata(IEnumerable<string> httpMethods, bool acceptCorsPreflight)
         {
             if (httpMethods == null)
@@ -27,8 +45,15 @@ namespace Microsoft.AspNetCore.Routing
             AcceptCorsPreflight = acceptCorsPreflight;
         }
 
+        /// <summary>
+        /// Returns a value indicating whether the associated endpoint should accept CORS preflight requests.
+        /// </summary>
         public bool AcceptCorsPreflight { get; }
 
+        /// <summary>
+        /// Returns a read-only collection of HTTP methods used during routing.
+        /// An empty collection means any HTTP method will be accepted.
+        /// </summary>
         public IReadOnlyList<string> HttpMethods { get; }
 
         private string DebuggerToString()

src/Microsoft.AspNetCore.Routing/IHttpMethodMetadata.cs

@@ -5,10 +5,20 @@ using System.Collections.Generic;
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents HTTP method metadata used during routing.
+    /// </summary>
     public interface IHttpMethodMetadata
     {
+        /// <summary>
+        /// Returns a value indicating whether the associated endpoint should accept CORS preflight requests.
+        /// </summary>
         bool AcceptCorsPreflight { get; }
 
+        /// <summary>
+        /// Returns a read-only collection of HTTP methods used during routing.
+        /// An empty collection means any HTTP method will be accepted.
+        /// </summary>
         IReadOnlyList<string> HttpMethods { get; }
     }
 }

src/Microsoft.AspNetCore.Routing/ISuppressLinkGenerationMetadata.cs

@@ -3,6 +3,10 @@
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents metadata used during link generation.
+    /// The associated endpoint will not be considered for link generation.
+    /// </summary>
     public interface ISuppressLinkGenerationMetadata
     {
     }

src/Microsoft.AspNetCore.Routing/SuppressLinkGenerationMetadata.cs

@@ -3,6 +3,10 @@
 
 namespace Microsoft.AspNetCore.Routing
 {
+    /// <summary>
+    /// Represents metadata used during link generation.
+    /// The associated endpoint will not be considered for link generation.
+    /// </summary>
     public sealed class SuppressLinkGenerationMetadata : ISuppressLinkGenerationMetadata
     {
     }