Add doc strings for public APIs in Http.Abstractions and Routing.Abstractions (#26468)

* Add doc strings to Http.Abstractions and Routing.Abstractions

* Address feedback from peer review

* Update src/Http/Http.Abstractions/src/ConnectionInfo.cs

Co-authored-by: James Newton-King <[email protected]>

Co-authored-by: James Newton-King <[email protected]>

Author: captainsafia

src/Http/Http.Abstractions/src/ConnectionInfo.cs

@@ -8,23 +8,45 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Represents the underlying connection for a request.
+    /// </summary>
     public abstract class ConnectionInfo
     {
         /// <summary>
         /// Gets or sets a unique identifier to represent this connection.
         /// </summary>
         public abstract string Id { get; set; }
 
+        /// <summary>
+        /// Gets or sets the IP address of the remote target. Can be null.
+        /// </summary>
         public abstract IPAddress? RemoteIpAddress { get; set; }
 
+        /// <summary>
+        /// Gets or sets the port of the remote target.
+        /// </summary>
         public abstract int RemotePort { get; set; }
 
+        /// <summary>
+        /// Gets or sets the IP address of the local host.
+        /// </summary>
         public abstract IPAddress? LocalIpAddress { get; set; }
 
+        /// <summary>
+        /// Gets or sets the port of the local host.
+        /// </summary>
         public abstract int LocalPort { get; set; }
 
+        /// <summary>
+        /// Gets or sets the client certificate.
+        /// </summary>
         public abstract X509Certificate2? ClientCertificate { get; set; }
 
+        /// <summary>
+        /// Retrieves the client certificate.
+        /// </summary>
+        /// <returns>Asynchronously returns an <see cref="X509Certificate2" />. Can be null.</returns>
         public abstract Task<X509Certificate2?> GetClientCertificateAsync(CancellationToken cancellationToken = new CancellationToken());
     }
 }

src/Http/Http.Abstractions/src/Extensions/HeaderDictionaryExtensions.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Contains extension methods for modifying an <see cref="IHeaderDictionary"/> instance.
+    /// </summary>
     public static class HeaderDictionaryExtensions
     {
         /// <summary>

src/Http/Http.Abstractions/src/Extensions/ResponseTrailerExtensions.cs

@@ -8,6 +8,10 @@
 
 namespace Microsoft.AspNetCore.Http
 {
+    /// <summary>
+    /// Contains extension methods for modifying the `Trailer` response header
+    /// and trailing headers in an <see cref="HttpResponse" />.
+    /// </summary>
     public static class ResponseTrailerExtensions
     {
         /// <summary>

src/Http/Http.Abstractions/src/FragmentString.cs

@@ -105,6 +105,11 @@ public static FragmentString FromUriComponent(Uri uri)
             return new FragmentString(fragmentValue);
         }
 
+        /// <summary>
+        /// Evaluates if the current fragment is equal to another fragment <paramref name="other"/>.
+        /// </summary>
+        /// <param name="other">A <see cref="FragmentString" /> to compare.</param>
+        /// <returns><see langword="true" /> if the fragments are equal.</returns>
         public bool Equals(FragmentString other)
         {
             if (!HasValue && !other.HasValue)
@@ -114,6 +119,11 @@ public bool Equals(FragmentString other)
             return string.Equals(_value, other._value, StringComparison.Ordinal);
         }
 
+        /// <summary>
+        /// Evaluates if the current fragment is equal to an object <paramref name="obj"/>.
+        /// </summary>
+        /// <param name="obj">An object to compare.</param>
+        /// <returns><see langword="true" /> if the fragments are equal.</returns>
         public override bool Equals(object? obj)
         {
             if (ReferenceEquals(null, obj))
@@ -123,16 +133,32 @@ public override bool Equals(object? obj)
             return obj is FragmentString && Equals((FragmentString)obj);
         }
 
+        /// <summary>
+        /// Gets a hash code for the value.
+        /// </summary>
+        /// <returns>The hash code as an <see cref="int"/>.</returns>
         public override int GetHashCode()
         {
             return (HasValue ? _value.GetHashCode() : 0);
         }
 
+        /// <summary>
+        /// Evaluates if one fragment is equal to another.
+        /// </summary>
+        /// <param name="left">A <see cref="FragmentString"/> instance.</param>
+        /// <param name="right">A <see cref="FragmentString"/> instance.</param>
+        /// <returns><see langword="true" /> if the fragments are equal.</returns>
         public static bool operator ==(FragmentString left, FragmentString right)
         {
             return left.Equals(right);
         }
 
+        /// <summary>
+        /// Evalutes if one framgent is not equal to another.
+        /// </summary>
+        /// <param name="left">A <see cref="FragmentString"/> instance.</param>
+        /// <param name="right">A <see cref="FragmentString"/> instance.</param>
+        /// <returns><see langword="true" /> if the fragments are not equal.</returns>
         public static bool operator !=(FragmentString left, FragmentString right)
         {
             return !left.Equals(right);

src/Http/Http.Abstractions/src/HostString.cs

@@ -65,6 +65,9 @@ public string Value
             get { return _value; }
         }
 
+        /// <summary>
+        /// Returns true if the host is set.
+        /// </summary>
         public bool HasValue
         {
             get { return !string.IsNullOrEmpty(_value); }

src/Http/Http.Abstractions/src/HttpMethods.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.AspNetCore.Http
 {
     /// <summary>
-    /// Contains methods to verify the request method of an HTTP request. 
+    /// Contains methods to verify the request method of an HTTP request.
     /// </summary>
     public static class HttpMethods
     {
@@ -18,18 +18,45 @@ public static class HttpMethods
         // and allow us to optimize comparisons when these constants are used.
 
         // Please do NOT change these to 'const'
+        /// <summary>
+        /// HTTP "CONNECT" method.
+        /// </summary>
         public static readonly string Connect = "CONNECT";
+        /// <summary>
+        /// HTTP "DELETE" method.
+        /// </summary>
         public static readonly string Delete = "DELETE";
+        /// <summary>
+        /// HTTP "GET" method.
+        /// </summary>
         public static readonly string Get = "GET";
+        /// <summary>
+        /// HTTP "HEAD" method.
+        /// </summary>
         public static readonly string Head = "HEAD";
+        /// <summary>
+        /// HTTP "OPTIONS" method.
+        /// </summary>
         public static readonly string Options = "OPTIONS";
+        /// <summary>
+        /// HTTP "PATCH" method.
+        /// </summary>
         public static readonly string Patch = "PATCH";
+        /// <summary>
+        /// HTTP "POST" method.
+        /// </summary>
         public static readonly string Post = "POST";
+        /// <summary>
+        /// HTTP "PUT" method.
+        /// </summary>
         public static readonly string Put = "PUT";
+        /// <summary>
+        /// HTTP "TRACE" method.
+        /// </summary>
         public static readonly string Trace = "TRACE";
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is CONNECT. 
+        /// Returns a value that indicates if the HTTP request method is CONNECT.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -41,7 +68,7 @@ public static bool IsConnect(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is DELETE. 
+        /// Returns a value that indicates if the HTTP request method is DELETE.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -53,7 +80,7 @@ public static bool IsDelete(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is GET. 
+        /// Returns a value that indicates if the HTTP request method is GET.
         /// </summary>
         /// <param name="method">The  HTTP request method.</param>
         /// <returns>
@@ -65,7 +92,7 @@ public static bool IsGet(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is HEAD. 
+        /// Returns a value that indicates if the HTTP request method is HEAD.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -77,7 +104,7 @@ public static bool IsHead(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is OPTIONS. 
+        /// Returns a value that indicates if the HTTP request method is OPTIONS.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -89,7 +116,7 @@ public static bool IsOptions(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is PATCH. 
+        /// Returns a value that indicates if the HTTP request method is PATCH.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -101,7 +128,7 @@ public static bool IsPatch(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is POST. 
+        /// Returns a value that indicates if the HTTP request method is POST.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -113,7 +140,7 @@ public static bool IsPost(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is PUT. 
+        /// Returns a value that indicates if the HTTP request method is PUT.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -125,7 +152,7 @@ public static bool IsPut(string method)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request method is TRACE. 
+        /// Returns a value that indicates if the HTTP request method is TRACE.
         /// </summary>
         /// <param name="method">The HTTP request method.</param>
         /// <returns>
@@ -156,7 +183,7 @@ string _ when IsConnect(method) => Connect,
         };
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP methods are the same. 
+        /// Returns a value that indicates if the HTTP methods are the same.
         /// </summary>
         /// <param name="methodA">The first HTTP request method to compare.</param>
         /// <param name="methodB">The second HTTP request method to compare.</param>

src/Http/Http.Abstractions/src/HttpProtocol.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.AspNetCore.Http
 {
     /// <summary>
-    /// Contains methods to verify the request protocol version of an HTTP request. 
+    /// Contains methods to verify the request protocol version of an HTTP request.
     /// </summary>
     public static class HttpProtocol
     {
@@ -18,13 +18,26 @@ public static class HttpProtocol
         // and allow us to optimize comparisons when these constants are used.
 
         // Please do NOT change these to 'const'
+
+        /// <summary>
+        ///  HTTP protocol version 1.0.
+        /// </summary>
         public static readonly string Http10 = "HTTP/1.0";
+        /// <summary>
+        ///  HTTP protocol version 1.1.
+        /// </summary>
         public static readonly string Http11 = "HTTP/1.1";
+        /// <summary>
+        ///  HTTP protocol version 2.
+        /// </summary>
         public static readonly string Http2 = "HTTP/2";
+        /// <summary>
+        ///  HTTP protcol version 3.
+        /// </summary>
         public static readonly string Http3 = "HTTP/3";
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request protocol is HTTP/1.0. 
+        /// Returns a value that indicates if the HTTP request protocol is HTTP/1.0.
         /// </summary>
         /// <param name="protocol">The HTTP request protocol.</param>
         /// <returns>
@@ -36,7 +49,7 @@ public static bool IsHttp10(string protocol)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request protocol is HTTP/1.1. 
+        /// Returns a value that indicates if the HTTP request protocol is HTTP/1.1.
         /// </summary>
         /// <param name="protocol">The HTTP request protocol.</param>
         /// <returns>
@@ -48,7 +61,7 @@ public static bool IsHttp11(string protocol)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request protocol is HTTP/2. 
+        /// Returns a value that indicates if the HTTP request protocol is HTTP/2.
         /// </summary>
         /// <param name="protocol">The HTTP request protocol.</param>
         /// <returns>
@@ -60,7 +73,7 @@ public static bool IsHttp2(string protocol)
         }
 
         /// <summary>
-        /// Returns a value that indicates if the HTTP request protocol is HTTP/3. 
+        /// Returns a value that indicates if the HTTP request protocol is HTTP/3.
         /// </summary>
         /// <param name="protocol">The HTTP request protocol.</param>
         /// <returns>

src/Http/Http.Abstractions/src/Microsoft.AspNetCore.Http.Abstractions.csproj

@@ -12,7 +12,7 @@ Microsoft.AspNetCore.Http.HttpResponse</Description>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore</PackageTags>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <IsPackable>false</IsPackable>
     <Nullable>enable</Nullable>
   </PropertyGroup>