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; }
     }
-}
+}