API docs for IIS (#26387)

Author: jkotalik

src/Servers/IIS/IIS/src/BadHttpRequestException.cs

@@ -8,6 +8,7 @@
 
 namespace Microsoft.AspNetCore.Server.IIS
 {
+    ///<inheritdoc/>
     [Obsolete("Moved to Microsoft.AspNetCore.Http.BadHttpRequestException")]
     public sealed class BadHttpRequestException : Microsoft.AspNetCore.Http.BadHttpRequestException
     {
@@ -17,6 +18,7 @@ internal BadHttpRequestException(string message, int statusCode, RequestRejectio
             Reason = reason;
         }
 
+        ///<inheritdoc/>
         public new int StatusCode { get => base.StatusCode; }
 
         internal RequestRejectionReason Reason { get; }

src/Servers/IIS/IIS/src/Core/IISServerAuthenticationHandler.cs

@@ -8,13 +8,17 @@
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// The default authentication handler with IIS In-Process
+    /// </summary>
     public class IISServerAuthenticationHandler : IAuthenticationHandler
     {
         private HttpContext _context;
         private IISHttpContext _iisHttpContext;
 
         internal AuthenticationScheme Scheme { get; private set; }
 
+        ///<inheritdoc/>
         public Task<AuthenticateResult> AuthenticateAsync()
         {
             var user = _iisHttpContext.WindowsUser;
@@ -28,19 +32,22 @@ public Task<AuthenticateResult> AuthenticateAsync()
             }
         }
 
+        ///<inheritdoc/>
         public Task ChallengeAsync(AuthenticationProperties properties)
         {
             // We would normally set the www-authenticate header here, but IIS does that for us.
             _context.Response.StatusCode = 401;
             return Task.CompletedTask;
         }
 
+        ///<inheritdoc/>
         public Task ForbidAsync(AuthenticationProperties properties)
         {
             _context.Response.StatusCode = 403;
             return Task.CompletedTask;
         }
 
+        ///<inheritdoc/>
         public Task InitializeAsync(AuthenticationScheme scheme, HttpContext context)
         {
             _iisHttpContext = context.Features.Get<IISHttpContext>();

src/Servers/IIS/IIS/src/Core/ThrowingWasUpgradedWriteOnlyStream.cs

@@ -8,20 +8,31 @@
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// A <see cref="Stream"/> which throws on calls to write after the stream was upgraded
+    /// </summary>
+    /// <remarks>
+    /// Users should not need to instantiate this class.
+    /// </remarks>
     public class ThrowingWasUpgradedWriteOnlyStream : WriteOnlyStream
     {
+        ///<inheritdoc/>
         public override void Write(byte[] buffer, int offset, int count)
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override void Flush()
             => throw new InvalidOperationException(CoreStrings.ResponseStreamWasUpgraded);
 
+        ///<inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
             => throw new NotSupportedException();
 
+        ///<inheritdoc/>
         public override void SetLength(long value)
             => throw new NotSupportedException();
     }

src/Servers/IIS/IIS/src/Core/WriteOnlyStream.cs

@@ -8,43 +8,56 @@
 
 namespace Microsoft.AspNetCore.Server.IIS.Core
 {
+    /// <summary>
+    /// A <see cref="Stream"/> which only allows for writes.
+    /// </summary>
     public abstract class WriteOnlyStream : Stream
     {
+        ///<inheritdoc/>
         public override bool CanRead => false;
 
+        ///<inheritdoc/>
         public override bool CanWrite => true;
 
+        ///<inheritdoc/>
         public override int ReadTimeout
         {
             get => throw new NotSupportedException();
             set => throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override bool CanSeek => false;
 
+        ///<inheritdoc/>
         public override long Length => throw new NotSupportedException();
 
+        ///<inheritdoc/>
         public override long Position
         {
             get => throw new NotSupportedException();
             set => throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override int Read(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override long Seek(long offset, SeekOrigin origin)
         {
             throw new NotSupportedException();
         }
 
+        ///<inheritdoc/>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();

src/Servers/IIS/IIS/src/IISServerDefaults.cs

@@ -3,8 +3,14 @@
 
 namespace Microsoft.AspNetCore.Server.IIS
 {
+    /// <summary>
+    /// String constants used to configure IIS In-Process.
+    /// </summary>
     public class IISServerDefaults
     {
+        /// <summary>
+        /// Default authentication scheme, which is "Windows".
+        /// </summary>
         public const string AuthenticationScheme = "Windows";
     }
 }

src/Servers/IIS/IIS/src/IISServerOptions.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Provides configuration for IIS In-Process.
+    /// </summary>
     public class IISServerOptions
     {
         /// <summary>

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

@@ -5,14 +5,14 @@
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
     <PackageId>Microsoft.AspNetCore.Server.IIS</PackageId>
     <Description>Provides support for hosting ASP.NET Core in IIS using the AspNetCoreModule.</Description>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;iis</PackageTags>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <NativeAssetsTargetFramework>$(DefaultNetCoreTargetFramework)</NativeAssetsTargetFramework>
     <IsPackable>false</IsPackable>
 
     <!-- Ignore platform compatibility warnings for this project. We know this only works on windows.-->
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <NoWarn>$(NoWarn);CA1416</NoWarn>
   </PropertyGroup>
 

src/Servers/IIS/IIS/src/WebHostBuilderIISExtensions.cs

@@ -12,14 +12,17 @@
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Extension methods for the IIS In-Process.
+    /// </summary>
     public static class WebHostBuilderIISExtensions
     {
         /// <summary>
         /// Configures the port and base path the server should listen on when running behind AspNetCoreModule.
         /// The app will also be configured to capture startup errors.
         /// </summary>
-        /// <param name="hostBuilder"></param>
-        /// <returns></returns>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
         public static IWebHostBuilder UseIIS(this IWebHostBuilder hostBuilder)
         {
             if (hostBuilder == null)

src/Servers/IIS/IISIntegration/src/IISDefaults.cs

@@ -3,10 +3,22 @@
 
 namespace Microsoft.AspNetCore.Server.IISIntegration
 {
+    /// <summary>
+    /// String constants used to configure IIS Out-Of-Process.
+    /// </summary>
     public class IISDefaults
     {
+        /// <summary>
+        /// Default authentication scheme, which is "Windows".
+        /// </summary>
         public const string AuthenticationScheme = "Windows";
+        /// <summary>
+        /// Default negotiate string, which is "Negotiate".
+        /// </summary>
         public const string Negotiate = "Negotiate";
+        /// <summary>
+        /// Default NTLM string, which is "NTLM".
+        /// </summary>
         public const string Ntlm = "NTLM";
     }
 }

src/Servers/IIS/IISIntegration/src/IISHostingStartup.cs

@@ -7,8 +7,18 @@
 
 namespace Microsoft.AspNetCore.Server.IISIntegration
 {
+    /// <summary>
+    /// The <see cref="IHostingStartup"/> to add IISIntegration to apps.
+    /// </summary>
+    /// <remarks>
+    /// This API isn't meant to be used by user code.
+    /// </remarks>
     public class IISHostingStartup : IHostingStartup
     {
+        /// <summary>
+        /// Adds IISIntegration into the middleware pipeline.
+        /// </summary>
+        /// <param name="builder">The <see cref="IWebHostBuilder"/>.</param>
         public void Configure(IWebHostBuilder builder)
         {
             builder.UseIISIntegration();