Api docs for Diagnostics middlewares (#26525)

* Api docs for Diagnostics middlewares

* Update ExceptionHandlerFeature.cs

* Update StatusCodePagesMiddleware.cs

* Update ExceptionHandlerMiddleware.cs

* Apply suggestions from code review

Co-authored-by: Pranav K <prkrishn@hotmail.com>

Co-authored-by: Pranav K <prkrishn@hotmail.com>

src/Middleware/Diagnostics.Abstractions/src/DiagnosticMessage.cs

@@ -8,6 +8,16 @@ namespace Microsoft.AspNetCore.Diagnostics
     /// </summary>
     public class DiagnosticMessage
     {
+        /// <summary>
+        /// Initializes a new instance of <see cref="DiagnosticMessage"/>.
+        /// </summary>
+        /// <param name="message">The error message.</param>
+        /// <param name="formattedMessage">The formatted error message.</param>
+        /// <param name="filePath">The path of the file that produced the message.</param>
+        /// <param name="startLine">The one-based line index for the start of the compilation error.</param>
+        /// <param name="startColumn">The zero-based column index for the start of the compilation error.</param>
+        /// <param name="endLine">The one-based line index for the end of the compilation error.</param>
+        /// <param name="endColumn">The zero-based column index for the end of the compilation error.</param>
         public DiagnosticMessage(
             string message,
             string formattedMessage,
@@ -61,4 +71,4 @@ namespace Microsoft.AspNetCore.Diagnostics
         /// </summary>
         public string FormattedMessage { get; }
     }
-}
+}

src/Middleware/Diagnostics.Abstractions/src/IExceptionHandlerFeature.cs

@@ -5,8 +5,14 @@ using System;
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// Represents a feature containing the error of the original request to be examined by an exception handler.
+    /// </summary>
     public interface IExceptionHandlerFeature
     {
+        /// <summary>
+        /// The error encountered during the original request
+        /// </summary>
         Exception Error { get; }
     }
-}
+}

src/Middleware/Diagnostics.Abstractions/src/IStatusCodeReExecuteFeature.cs

@@ -1,14 +1,30 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using Microsoft.AspNetCore.Http;
+
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// Represents a feature containing the path details of the original request. This feature is provided by the
+    /// StatusCodePagesMiddleware when it re-execute the request pipeline with an alternative path to generate the
+    /// response body.
+    /// </summary>
     public interface IStatusCodeReExecuteFeature
     {
+        /// <summary>
+        /// The <see cref="HttpRequest.PathBase"/> of the original request.
+        /// </summary>
         string OriginalPathBase { get; set; }
 
+        /// <summary>
+        /// The <see cref="HttpRequest.Path"/> of the original request.
+        /// </summary>
         string OriginalPath { get; set; }
 
+        /// <summary>
+        /// The <see cref="HttpRequest.QueryString"/> of the original request.
+        /// </summary>
         string OriginalQueryString { get; set; }
     }
-}
+}

src/Middleware/Diagnostics.Abstractions/src/Microsoft.AspNetCore.Diagnostics.Abstractions.csproj

@@ -4,7 +4,7 @@
     <Description>ASP.NET Core diagnostics middleware abstractions and feature interface definitions.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;diagnostics</PackageTags>
     <IsPackable>false</IsPackable>

src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerExtensions.cs

@@ -8,6 +8,9 @@ using Microsoft.Extensions.Options;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Extension methods for enabling <see cref="ExceptionHandlerExtensions"/>.
+    /// </summary>
     public static class ExceptionHandlerExtensions
     {
         /// <summary>
@@ -95,4 +98,4 @@ namespace Microsoft.AspNetCore.Builder
             return app.UseMiddleware<ExceptionHandlerMiddleware>(Options.Create(options));
         }
     }
-}
+}

src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerFeature.cs

@@ -5,10 +5,15 @@ using System;
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// A feature containing the path and error of the original request for examination by an exception handler.
+    /// </summary>
     public class ExceptionHandlerFeature : IExceptionHandlerPathFeature
     {
+        /// <inheritdoc/>
         public Exception Error { get; set; }
 
+        /// <inheritdoc/>
         public string Path { get; set; }
     }
-}
+}

src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerMiddleware.cs

@@ -14,6 +14,9 @@ using Microsoft.Net.Http.Headers;
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// A middleware for handling exceptions in the application.
+    /// </summary>
     public class ExceptionHandlerMiddleware
     {
         private readonly RequestDelegate _next;
@@ -22,6 +25,13 @@ namespace Microsoft.AspNetCore.Diagnostics
         private readonly Func<object, Task> _clearCacheHeadersDelegate;
         private readonly DiagnosticListener _diagnosticListener;
 
+        /// <summary>
+        /// Creates a new <see cref="ExceptionHandlerMiddleware"/>
+        /// </summary>
+        /// <param name="next">The <see cref="RequestDelegate"/> representing the next middleware in the pipeline.</param>
+        /// <param name="loggerFactory">The <see cref="ILoggerFactory"/> used for logging.</param>
+        /// <param name="options">The options for configuring the middleware.</param>
+        /// <param name="diagnosticListener">The <see cref="DiagnosticListener"/> used for writing diagnostic messages.</param>
         public ExceptionHandlerMiddleware(
             RequestDelegate next,
             ILoggerFactory loggerFactory,
@@ -46,6 +56,10 @@ namespace Microsoft.AspNetCore.Diagnostics
             }
         }
 
+        /// <summary>
+        /// Executes the middleware.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
         public Task Invoke(HttpContext context)
         {
             ExceptionDispatchInfo edi;

src/Middleware/Diagnostics/src/ExceptionHandler/ExceptionHandlerOptions.cs

@@ -1,14 +1,26 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using Microsoft.AspNetCore.Diagnostics;
 using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Options for configuring the <see cref="ExceptionHandlerMiddleware"/>.
+    /// </summary>
     public class ExceptionHandlerOptions
     {
+        /// <summary>
+        /// The path to the exception handling endpoint. This path will be used when executing
+        /// the <see cref="ExceptionHandler"/>.
+        /// </summary>
         public PathString ExceptionHandlingPath { get; set; }
 
+        /// <summary>
+        /// The <see cref="RequestDelegate" /> that will handle the exception. If this is not
+        /// explicitly provided, the subsequent middleware pipeline will be used by default.
+        /// </summary>
         public RequestDelegate ExceptionHandler { get; set; }
     }
-}
+}

src/Middleware/Diagnostics/src/Microsoft.AspNetCore.Diagnostics.csproj

@@ -4,7 +4,7 @@
     <Description>ASP.NET Core middleware for exception handling, exception display pages, and diagnostics information. Includes developer exception page middleware, exception handler middleware, runtime info middleware, status code page middleware, and welcome page middleware</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;diagnostics</PackageTags>
     <IsPackable>false</IsPackable>

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodeContext.cs

@@ -6,8 +6,17 @@ using Microsoft.AspNetCore.Http;
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// Contains information used by the handler of the <see cref="StatusCodePagesMiddleware"/>.
+    /// </summary>
     public class StatusCodeContext
     {
+        /// <summary>
+        /// Creates a new <see cref="StatusCodeContext"/>.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/>.</param>
+        /// <param name="options">The configured <see cref="StatusCodePagesOptions"/>.</param>
+        /// <param name="next">The <see cref="RequestDelegate"/> representing the next middleware in the pipeline.</param>
         public StatusCodeContext(HttpContext context, StatusCodePagesOptions options, RequestDelegate next)
         {
             HttpContext = context;
@@ -15,10 +24,19 @@ namespace Microsoft.AspNetCore.Diagnostics
             Next = next;
         }
 
+        /// <summary>
+        /// Gets the <see cref="HttpContext"/>.
+        /// </summary>
         public HttpContext HttpContext { get; private set; }
 
+        /// <summary>
+        /// Gets the configured <see cref="StatusCodePagesOptions"/>.
+        /// </summary>
         public StatusCodePagesOptions Options { get; private set; }
 
+        /// <summary>
+        /// Gets the <see cref="RequestDelegate"/> representing the next middleware in the pipeline.
+        /// </summary>
         public RequestDelegate Next { get; private set; }
     }
-}
+}

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesExtensions.cs

@@ -11,6 +11,9 @@ using Microsoft.Extensions.Options;
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Extension methods for enabling <see cref="StatusCodePagesMiddleware"/>.
+    /// </summary>
     public static class StatusCodePagesExtensions
     {
         /// <summary>

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesFeature.cs

@@ -8,6 +8,11 @@ namespace Microsoft.AspNetCore.Diagnostics
     /// </summary>
     public class StatusCodePagesFeature : IStatusCodePagesFeature
     {
+        /// <summary>
+        /// Enables or disables status code pages. The default value is true.
+        /// Set this to false to prevent the <see cref="StatusCodePagesMiddleware"/>
+        /// from creating a response body while handling the error status code.
+        /// </summary>
         public bool Enabled { get; set; } = true;
     }
-}
+}

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesMiddleware.cs

@@ -9,11 +9,19 @@ using Microsoft.Extensions.Options;
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>
+    /// A middleware for generating the response body of error status codes with no body.
+    /// </summary>
     public class StatusCodePagesMiddleware
     {
         private readonly RequestDelegate _next;
         private readonly StatusCodePagesOptions _options;
 
+        /// <summary>
+        /// Creates a new <see cref="StatusCodePagesMiddleware"/>
+        /// </summary>
+        /// <param name="next">The <see cref="RequestDelegate"/> representing the next middleware in the pipeline.</param>
+        /// <param name="options">The options for configuring the middleware.</param>
         public StatusCodePagesMiddleware(RequestDelegate next, IOptions<StatusCodePagesOptions> options)
         {
             _next = next;
@@ -24,6 +32,11 @@ namespace Microsoft.AspNetCore.Diagnostics
             }
         }
 
+        /// <summary>
+        /// Executes the middleware.
+        /// </summary>
+        /// <param name="context">The <see cref="HttpContext"/> for the current request.</param>
+        /// <returns>A task that represents the execution of this middleware.</returns>
         public async Task Invoke(HttpContext context)
         {
             var statusCodeFeature = new StatusCodePagesFeature();
@@ -52,4 +65,4 @@ namespace Microsoft.AspNetCore.Diagnostics
             await _options.HandleAsync(statusCodeContext);
         }
     }
-}
+}

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodePagesOptions.cs

@@ -11,10 +11,14 @@ using Microsoft.AspNetCore.WebUtilities;
 namespace Microsoft.AspNetCore.Builder
 {
     /// <summary>
-    /// Options for StatusCodePagesMiddleware.
+    /// Options for <see cref="StatusCodePagesMiddleware"/>.
     /// </summary>
     public class StatusCodePagesOptions
     {
+        /// <summary>
+        /// Creates a default <see cref="StatusCodePagesOptions"/> which produces a plaintext response
+        /// containing the status code and the reason phrase.
+        /// </summary>
         public StatusCodePagesOptions()
         {
             HandleAsync = context =>
@@ -43,6 +47,9 @@ namespace Microsoft.AspNetCore.Builder
                                                                     internetExplorerWorkaround);
         }
 
+        /// <summary>
+        /// The handler that generates the response body for the given <see cref="StatusCodeContext"/>. By default this produces a plain text response that includes the status code.
+        /// </summary>
         public Func<StatusCodeContext, Task> HandleAsync { get; set; }
     }
-}
+}

src/Middleware/Diagnostics/src/StatusCodePage/StatusCodeReExecuteFeature.cs

@@ -3,12 +3,16 @@
 
 namespace Microsoft.AspNetCore.Diagnostics
 {
+    /// <summary>Default implementation for <see cref="IStatusCodeReExecuteFeature" />.</summary>
     public class StatusCodeReExecuteFeature : IStatusCodeReExecuteFeature
     {
+        /// <inheritdoc/>
         public string OriginalPath { get; set; }
 
+        /// <inheritdoc/>
         public string OriginalPathBase { get; set; }
 
+        /// <inheritdoc/>
         public string OriginalQueryString { get; set; }
     }
-}
+}