From 5ee3ae90023c691c80e89a0ae059f1cc8828b614 Mon Sep 17 00:00:00 2001
From: James Newton-King <james@newtonking.com>
Date: Sat, 4 Aug 2018 13:34:25 +1200
Subject: [PATCH] Add XML docs to data sources and metadata (#692)

---
 .../CompositeEndpointDataSource.cs            | 11 ++++++++
 .../DefaultEndpointDataSource.cs              | 19 ++++++++++++++
 .../EndpointDataSource.cs                     | 11 ++++++++
 .../HttpMethodMetadata.cs                     | 25 +++++++++++++++++++
 .../IHttpMethodMetadata.cs                    | 10 ++++++++
 .../ISuppressLinkGenerationMetadata.cs        |  4 +++
 .../SuppressLinkGenerationMetadata.cs         |  4 +++
 7 files changed, 84 insertions(+)

diff --git a/src/Microsoft.AspNetCore.Routing/CompositeEndpointDataSource.cs b/src/Microsoft.AspNetCore.Routing/CompositeEndpointDataSource.cs
index 3341b21796..b247291db4 100644
--- a/src/Microsoft.AspNetCore.Routing/CompositeEndpointDataSource.cs
+++ b/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
diff --git a/src/Microsoft.AspNetCore.Routing/DefaultEndpointDataSource.cs b/src/Microsoft.AspNetCore.Routing/DefaultEndpointDataSource.cs
index b73b8fcc0b..7ec3f4c6e6 100644
--- a/src/Microsoft.AspNetCore.Routing/DefaultEndpointDataSource.cs
+++ b/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;
     }
 }
diff --git a/src/Microsoft.AspNetCore.Routing/EndpointDataSource.cs b/src/Microsoft.AspNetCore.Routing/EndpointDataSource.cs
index b5a1c40ebe..6ae887d0a0 100644
--- a/src/Microsoft.AspNetCore.Routing/EndpointDataSource.cs
+++ b/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; }
     }
 }
diff --git a/src/Microsoft.AspNetCore.Routing/HttpMethodMetadata.cs b/src/Microsoft.AspNetCore.Routing/HttpMethodMetadata.cs
index 7d76b56cd0..f01bf2a2a5 100644
--- a/src/Microsoft.AspNetCore.Routing/HttpMethodMetadata.cs
+++ b/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()
diff --git a/src/Microsoft.AspNetCore.Routing/IHttpMethodMetadata.cs b/src/Microsoft.AspNetCore.Routing/IHttpMethodMetadata.cs
index 83b99d8f72..af67c6e952 100644
--- a/src/Microsoft.AspNetCore.Routing/IHttpMethodMetadata.cs
+++ b/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; }
     }
 }
diff --git a/src/Microsoft.AspNetCore.Routing/ISuppressLinkGenerationMetadata.cs b/src/Microsoft.AspNetCore.Routing/ISuppressLinkGenerationMetadata.cs
index 23c5e168d8..4725b1a8c2 100644
--- a/src/Microsoft.AspNetCore.Routing/ISuppressLinkGenerationMetadata.cs
+++ b/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
     {
     }
diff --git a/src/Microsoft.AspNetCore.Routing/SuppressLinkGenerationMetadata.cs b/src/Microsoft.AspNetCore.Routing/SuppressLinkGenerationMetadata.cs
index 599267c570..88efd9077f 100644
--- a/src/Microsoft.AspNetCore.Routing/SuppressLinkGenerationMetadata.cs
+++ b/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
     {
     }