Add API ref docs for HTTPSys (#26649)

* Add API ref docs for HTTPSys

* Spacing

* Feedback

Author: wtgodbe

src/Servers/HttpSys/src/AuthenticationSchemes.cs

@@ -5,15 +5,39 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
-    // REVIEW: this appears to be very similar to System.Net.AuthenticationSchemes
+    /// <summary>
+    /// Specifies protocols for authentication.
+    /// </summary>
     [Flags]
     public enum AuthenticationSchemes
     {
+        /// <summary>
+        /// No authentication is enabled. This should only be used when HttpSysOptions.Authentication.AllowAnonymous is enabled (see <see cref="AuthenticationManager.AllowAnonymous"/>).
+        /// </summary>
         None = 0x0,
+
+        /// <summary>
+        /// Specifies basic authentication.
+        /// </summary>
         Basic = 0x1,
+
+
         // Digest = 0x2, // TODO: Verify this is no longer supported by Http.Sys
+
+        /// <summary>
+        /// Specifies NTLM authentication.
+        /// </summary>
         NTLM = 0x4,
+
+        /// <summary>
+        /// Negotiates with the client to determine the authentication scheme. If both client and server support Kerberos, it is used;
+        /// otherwise, NTLM is used.
+        /// </summary>
         Negotiate = 0x8,
+
+        /// <summary>
+        /// Specifies Kerberos authentication.
+        /// </summary>
         Kerberos = 0x10
     }
 }

src/Servers/HttpSys/src/DelegationRule.cs

@@ -31,6 +31,7 @@ internal DelegationRule(string queueName, string urlPrefix, ILogger logger)
             Queue = new RequestQueue(queueName, UrlPrefix, _logger, receiver: true);
         }
 
+        /// <inheritdoc />
         public void Dispose()
         {
             Queue.UrlGroup?.Dispose();

src/Servers/HttpSys/src/HttpSysDefaults.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// Constants for HttpSys.
+    /// </summary>
     public static class HttpSysDefaults
     {
         /// <summary>

src/Servers/HttpSys/src/HttpSysException.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// Exception thrown by HttpSys when an error occurs
+    /// </summary>
     [SuppressMessage("Microsoft.Usage", "CA2237:MarkISerializableTypesWithSerializable")]
     public class HttpSysException : Win32Exception
     {
@@ -28,6 +31,7 @@ internal HttpSysException(int errorCode, string message)
 
         // the base class returns the HResult with this property
         // we need the Win32 Error Code, hence the override.
+        /// <inheritdoc />
         public override int ErrorCode
         {
             get

src/Servers/HttpSys/src/HttpSysOptions.cs

@@ -7,6 +7,9 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// Contains the options used by HttpSys.
+    /// </summary>
     public class HttpSysOptions
     {
         private const uint MaximumRequestQueueNameLength = 260;
@@ -26,6 +29,9 @@ public class HttpSysOptions
         private long? _maxRequestBodySize = DefaultMaxRequestBodySize;
         private string _requestQueueName;
 
+        /// <summary>
+        /// Initializes a new <see cref="HttpSysOptions"/>.
+        /// </summary>
         public HttpSysOptions()
         {
         }

src/Servers/HttpSys/src/IHttpSysRequestDelegationFeature.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// Interface for delegating requests to other Http.Sys request queues.
+    /// </summary>
     public interface IHttpSysRequestDelegationFeature
     {
         /// <summary>
@@ -15,6 +18,7 @@ public interface IHttpSysRequestDelegationFeature
         /// must not be read nor the response started before this is invoked. Check <see cref="CanDelegate"/>
         /// before invoking.
         /// </summary>
+        /// <param name="destination">The rule maintaining the handle to the destination queue.</param>
         void DelegateRequest(DelegationRule destination);
     }
 }

src/Servers/HttpSys/src/IServerDelegationFeature.cs

@@ -3,11 +3,16 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// This exposes the creation of delegation rules on request queues owned by the server.
+    /// </summary>
     public interface IServerDelegationFeature
     {
         /// <summary>
         /// Create a delegation rule on request queue owned by the server.
         /// </summary>
+        /// <param name="queueName">The name of the Http.Sys request queue.</param>
+        /// <param name="urlPrefix">The URL of the Http.Sys Url Prefix.</param>
         /// <returns>
         /// Creates a <see cref="DelegationRule"/> that can used to delegate individual requests.
         /// </returns>

src/Servers/HttpSys/src/Microsoft.AspNetCore.Server.HttpSys.csproj

@@ -12,6 +12,7 @@
 
     <!-- Ignore platform compatibility warnings for this project. We know this only works on windows.-->
     <NoWarn>$(NoWarn);CA1416</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>

src/Servers/HttpSys/src/UrlPrefix.cs

@@ -7,6 +7,9 @@
 
 namespace Microsoft.AspNetCore.Server.HttpSys
 {
+    /// <summary>
+    /// A set of URL parameters used to listen for incoming requests.
+    /// </summary>
     public class UrlPrefix
     {
         private UrlPrefix(bool isHttps, string scheme, string host, string port, int portValue, string path)
@@ -94,6 +97,10 @@ public static UrlPrefix Create(string scheme, string host, int? portValue, strin
             return new UrlPrefix(isHttps, scheme, host, port, portValue.Value, path);
         }
 
+        /// <summary>
+        /// http://msdn.microsoft.com/en-us/library/windows/desktop/aa364698(v=vs.85).aspx
+        /// </summary>
+        /// <param name="prefix">The string that the <see cref="UrlPrefix"/> will be created from.</param>
         public static UrlPrefix Create(string prefix)
         {
             string scheme = null;
@@ -146,26 +153,58 @@ public static UrlPrefix Create(string prefix)
             return Create(scheme, host, port, path);
         }
 
+        /// <summary>
+        /// Gets a value that determines if the prefix's scheme is HTTPS.
+        /// </summary>
         public bool IsHttps { get; }
+
+        /// <summary>
+        /// Gets the scheme used by the prefix.
+        /// </summary>
         public string Scheme { get; }
+
+        /// <summary>
+        /// Gets the host domain name used by the prefix.
+        /// </summary>
         public string Host { get; }
+
+        /// <summary>
+        /// Gets a string representation of the port used by the prefix.
+        /// </summary>
         public string Port { get; }
+
         internal string HostAndPort { get; }
+
+        /// <summary>
+        /// Gets an integer representation of the port used by the prefix.
+        /// </summary>
         public int PortValue { get; }
+
+        /// <summary>
+        /// Gets the path component of the prefix.
+        /// </summary>
         public string Path { get; }
+
         internal string PathWithoutTrailingSlash { get; }
+        
+        /// <summary>
+        /// Gets a string representation of the prefix
+        /// </summary>
         public string FullPrefix { get; }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
         {
             return string.Equals(FullPrefix, Convert.ToString(obj), StringComparison.OrdinalIgnoreCase);
         }
 
+        /// <inheritdoc />
         public override int GetHashCode()
         {
             return StringComparer.OrdinalIgnoreCase.GetHashCode(FullPrefix);
         }
 
+        /// <inheritdoc />
         public override string ToString()
         {
             return FullPrefix;

src/Servers/HttpSys/src/UrlPrefixCollection.cs

@@ -30,6 +30,7 @@ internal UrlPrefixCollection()
         {
         }
 
+        /// <inheritdoc />
         public int Count
         {
             get
@@ -41,16 +42,27 @@ public int Count
             }
         }
 
+        /// <summary>
+        /// Gets a value that determines if this collection is readOnly.
+        /// </summary>
         public bool IsReadOnly
         {
             get { return false; }
         }
 
+        /// <summary>
+        /// Creates a <see cref="UrlPrefix"/> from the given string, and adds it to this collection.
+        /// </summary>
+        /// <param name="prefix">The string representing the <see cref="UrlPrefix"/> to add to this collection.</param>
         public void Add(string prefix)
         {
             Add(UrlPrefix.Create(prefix));
         }
 
+        /// <summary>
+        /// Adds a <see cref="UrlPrefix"/> to this collection.
+        /// </summary>
+        /// <param name="item">The prefix to add to this collection.</param>
         public void Add(UrlPrefix item)
         {
             lock (_prefixes)
@@ -98,6 +110,7 @@ internal bool TryMatchLongestPrefix(bool isHttps, string host, string originalPa
             return found;
         }
 
+        /// <inheritdoc />
         public void Clear()
         {
             lock (_prefixes)
@@ -110,6 +123,7 @@ public void Clear()
             }
         }
 
+        /// <inheritdoc />
         public bool Contains(UrlPrefix item)
         {
             lock (_prefixes)
@@ -118,6 +132,7 @@ public bool Contains(UrlPrefix item)
             }
         }
 
+        /// <inheritdoc />
         public void CopyTo(UrlPrefix[] array, int arrayIndex)
         {
             lock (_prefixes)
@@ -126,11 +141,13 @@ public void CopyTo(UrlPrefix[] array, int arrayIndex)
             }
         }
 
+        /// <inheritdoc />
         public bool Remove(string prefix)
         {
             return Remove(UrlPrefix.Create(prefix));
         }
 
+        /// <inheritdoc />
         public bool Remove(UrlPrefix item)
         {
             lock (_prefixes)
@@ -156,6 +173,9 @@ public bool Remove(UrlPrefix item)
             }
         }
 
+        /// <summary>
+        /// Returns an enumerator that iterates through this collection.
+        /// </summary>
         public IEnumerator<UrlPrefix> GetEnumerator()
         {
             lock (_prefixes)