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 <[email protected]>

Co-authored-by: Pranav K <[email protected]>

Author: John Luo

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 @@ public DiagnosticMessage(
         /// </summary>
         public string FormattedMessage { get; }
     }
-}
+}

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

@@ -5,8 +5,14 @@
 
 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 @@
 
 namespace Microsoft.AspNetCore.Builder
 {
+    /// <summary>
+    /// Extension methods for enabling <see cref="ExceptionHandlerExtensions"/>.
+    /// </summary>
     public static class ExceptionHandlerExtensions
     {
         /// <summary>
@@ -95,4 +98,4 @@ public static IApplicationBuilder UseExceptionHandler(this IApplicationBuilder a
             return app.UseMiddleware<ExceptionHandlerMiddleware>(Options.Create(options));
         }
     }
-}
+}

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

@@ -5,10 +5,15 @@
 
 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 @@
 
 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 @@ public class ExceptionHandlerMiddleware
         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 @@ public ExceptionHandlerMiddleware(
             }
         }
 
+        /// <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,19 +6,37 @@
 
 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;
             Options = options;
             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 @@
 
 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 @@
 
 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 @@ public StatusCodePagesMiddleware(RequestDelegate next, IOptions<StatusCodePagesO
             }
         }
 
+        /// <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 @@ public async Task Invoke(HttpContext context)
             await _options.HandleAsync(statusCodeContext);
         }
     }
-}
+}

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

@@ -11,10 +11,14 @@
 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 @@ private string BuildResponseBody(int httpStatusCode)
                                                                     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; }
     }
-}
+}