📝 Add doc comments to database error page

src/Microsoft.AspNet.Diagnostics.Entity/DatabaseErrorPageExtensions.cs

@@ -8,33 +8,54 @@ using System;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// <see cref="IApplicationBuilder"/> extension methods for the <see cref="DatabaseErrorPageMiddleware"/>.
+    /// </summary>
     public static class DatabaseErrorPageExtensions
     {
-        public static IApplicationBuilder UseDatabaseErrorPage([NotNull] this IApplicationBuilder builder)
+        /// <summary>
+        /// Captures synchronous and asynchronous database related exceptions from the pipeline that may be resolved using Entity Framework
+        /// migrations. When these exceptions occur an HTML response with details of possible actions to resolve the issue is generated. The
+        /// options for the middleware are set to display the maximum amount of information available.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to register the middleware with.</param>
+        /// <returns>The same <see cref="IApplicationBuilder"/> instance so that multiple calls can be chained.</returns>
+        public static IApplicationBuilder UseDatabaseErrorPage([NotNull] this IApplicationBuilder app)
         {
-            Check.NotNull(builder, nameof(builder));
+            Check.NotNull(app, nameof(app));
 
-            return builder.UseDatabaseErrorPage(options => options.EnableAll());
+            return app.UseDatabaseErrorPage(options => options.EnableAll());
         }
 
-        public static IApplicationBuilder UseDatabaseErrorPage([NotNull] this IApplicationBuilder builder, [NotNull] Action<DatabaseErrorPageOptions> optionsAction)
+        /// <summary>
+        /// Captures synchronous and asynchronous database related exceptions from the pipeline that may be resolved using Entity Framework
+        /// migrations. When these exceptions occur an HTML response with details of possible actions to resolve the issue is generated.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to register the middleware with.</param>
+        /// <param name="optionsAction">An action to set the options for the middleware. All options are disabled by default.</param>
+        /// <returns>The same <see cref="IApplicationBuilder"/> instance so that multiple calls can be chained.</returns>
+        public static IApplicationBuilder UseDatabaseErrorPage([NotNull] this IApplicationBuilder app, [NotNull] Action<DatabaseErrorPageOptions> optionsAction)
         {
-            Check.NotNull(builder, nameof(builder));
+            Check.NotNull(app, nameof(app));
             Check.NotNull(optionsAction, nameof(optionsAction));
 
             var options = new DatabaseErrorPageOptions();
             optionsAction(options);
 
-            builder = builder.UseMiddleware<DatabaseErrorPageMiddleware>(options);
+            app = app.UseMiddleware<DatabaseErrorPageMiddleware>(options);
 
             if(options.EnableMigrationCommands)
             {
-                builder.UseMigrationsEndPoint(o => o.Path = options.MigrationsEndPointPath);
+                app.UseMigrationsEndPoint(o => o.Path = options.MigrationsEndPointPath);
             }
 
-            return builder;
+            return app;
         }
 
+        /// <summary>
+        /// Sets the options to display the maximum amount of information available.
+        /// </summary>
+        /// <param name="options">The options to be configured.</param>
         public static void EnableAll([NotNull] this DatabaseErrorPageOptions options)
         {
             Check.NotNull(options, nameof(options));

src/Microsoft.AspNet.Diagnostics.Entity/DatabaseErrorPageMiddleware.cs

@@ -17,6 +17,10 @@ using Microsoft.Extensions.Logging;
 
 namespace Microsoft.AspNet.Diagnostics.Entity
 {
+    /// <summary>
+    /// Captures synchronous and asynchronous database related exceptions from the pipeline that may be resolved using Entity Framework
+    /// migrations. When these exceptions occur an HTML response with details of possible actions to resolve the issue is generated.
+    /// </summary>
     public class DatabaseErrorPageMiddleware
     {
         private readonly RequestDelegate _next;
@@ -25,6 +29,16 @@ namespace Microsoft.AspNet.Diagnostics.Entity
         private readonly ILogger _logger;
         private readonly DataStoreErrorLoggerProvider _loggerProvider;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DatabaseErrorPageMiddleware"/> class
+        /// </summary>
+        /// <param name="next">Delegate to execute the next piece of middleware in the request pipeline.</param>
+        /// <param name="serviceProvider">The <see cref="IServiceProvider"/> to resolve services from.</param>
+        /// <param name="loggerFactory">
+        /// The <see cref="ILoggerFactory"/> for the application. This middleware both produces logging messages and 
+        /// consumes them to detect database related exception.
+        /// </param>
+        /// <param name="options">The options to control what information is displayed on the error page.</param>
         public DatabaseErrorPageMiddleware([NotNull] RequestDelegate next, [NotNull] IServiceProvider serviceProvider, [NotNull] ILoggerFactory loggerFactory, [NotNull] DatabaseErrorPageOptions options)
         {
             Check.NotNull(next, nameof(next));
@@ -41,6 +55,11 @@ namespace Microsoft.AspNet.Diagnostics.Entity
             loggerFactory.AddProvider(_loggerProvider);
         }
 
+        /// <summary>
+        /// Process an individual request.
+        /// </summary>
+        /// <param name="context">The context for the current request.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public virtual async Task Invoke([NotNull] HttpContext context)
         {
             Check.NotNull(context, "context");

src/Microsoft.AspNet.Diagnostics.Entity/DatabaseErrorPageOptions.cs

@@ -5,11 +5,34 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Diagnostics.Entity
 {
+    /// <summary>
+    /// Options for the <see cref="DatabaseErrorPageMiddleware"/>.
+    /// </summary>
     public class DatabaseErrorPageOptions
     {
+        /// <summary>
+        /// Gets or sets a value indicating whether details about the exception that occurred
+        /// are displayed on the error page.
+        /// </summary>
         public virtual bool ShowExceptionDetails { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the names of pending migrations are listed
+        /// on the error page.
+        /// </summary>
         public virtual bool ListMigrations { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the error page will allow the execution of
+        /// migrations related commands when they may help solve the current error.
+        /// </summary>
         public virtual bool EnableMigrationCommands { get; set; }
+
+        /// <summary>
+        /// Gets or sets the path that <see cref="MigrationsEndPointMiddleware"/> will listen
+        /// for requests to execute migrations commands. The middleware is only registered if
+        /// <see cref="EnableMigrationCommands"/> is set to true.
+        /// </summary>
         public virtual PathString MigrationsEndPointPath { get; set; }
     }
 }

src/Microsoft.AspNet.Diagnostics.Entity/MigrationsEndPointExtensions.cs

@@ -8,24 +8,38 @@ using Microsoft.AspNet.Diagnostics.Entity.Utilities;
 
 namespace Microsoft.AspNet.Builder
 {
+    /// <summary>
+    /// <see cref="IApplicationBuilder"/> extension methods for the <see cref="MigrationsEndPointMiddleware"/>.
+    /// </summary>
     public static class MigrationsEndPointExtensions
     {
-        public static IApplicationBuilder UseMigrationsEndPoint([NotNull] this IApplicationBuilder builder)
+        /// <summary>
+        /// Processes requests to execute migrations operations. The middleware will listen for requests made to <see cref="MigrationsEndPointOptions.DefaultPath"/>.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to register the middleware with.</param>
+        /// <returns>The same <see cref="IApplicationBuilder"/> instance so that multiple calls can be chained.</returns>
+        public static IApplicationBuilder UseMigrationsEndPoint([NotNull] this IApplicationBuilder app)
         {
-            Check.NotNull(builder, "builder");
+            Check.NotNull(app, "builder");
 
-            return builder.UseMigrationsEndPoint(options => { });
+            return app.UseMigrationsEndPoint(options => { });
         }
 
-        public static IApplicationBuilder UseMigrationsEndPoint([NotNull] this IApplicationBuilder builder, [NotNull] Action<MigrationsEndPointOptions> optionsAction)
+        /// <summary>
+        /// Processes requests to execute migrations operations. The middleware will listen for requests to the path configured in <paramref name="optionsAction"/>.
+        /// </summary>
+        /// <param name="app">The <see cref="IApplicationBuilder"/> to register the middleware with.</param>
+        /// <param name="optionsAction">An action to set the options for the middleware.</param>
+        /// <returns>The same <see cref="IApplicationBuilder"/> instance so that multiple calls can be chained.</returns>
+        public static IApplicationBuilder UseMigrationsEndPoint([NotNull] this IApplicationBuilder app, [NotNull] Action<MigrationsEndPointOptions> optionsAction)
         {
-            Check.NotNull(builder, "builder");
+            Check.NotNull(app, "builder");
             Check.NotNull(optionsAction, "optionsAction");
 
             var options = new MigrationsEndPointOptions();
             optionsAction(options);
 
-            return builder.UseMiddleware<MigrationsEndPointMiddleware>(options);
+            return app.UseMiddleware<MigrationsEndPointMiddleware>(options);
         }
     }
 }

src/Microsoft.AspNet.Diagnostics.Entity/MigrationsEndPointMiddleware.cs

@@ -13,6 +13,9 @@ using Microsoft.Extensions.Logging;
 
 namespace Microsoft.AspNet.Diagnostics.Entity
 {
+    /// <summary>
+    /// Processes requests to execute migrations operations. The middleware will listen for requests to the path configured in the supplied options.
+    /// </summary>
     public class MigrationsEndPointMiddleware
     {
         private readonly RequestDelegate _next;
@@ -20,6 +23,13 @@ namespace Microsoft.AspNet.Diagnostics.Entity
         private readonly ILogger _logger;
         private readonly MigrationsEndPointOptions _options;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MigrationsEndPointMiddleware"/> class
+        /// </summary>
+        /// <param name="next">Delegate to execute the next piece of middleware in the request pipeline.</param>
+        /// <param name="serviceProvider">The <see cref="IServiceProvider"/> to resolve services from.</param>
+        /// <param name="logger">The <see cref="Logger{T}"/> to write messages to.</param>
+        /// <param name="options">The options to control the behavior of the middleware.</param>
         public MigrationsEndPointMiddleware(
             [NotNull] RequestDelegate next, 
             [NotNull] IServiceProvider serviceProvider, 
@@ -37,6 +47,11 @@ namespace Microsoft.AspNet.Diagnostics.Entity
             _options = options;
         }
 
+        /// <summary>
+        /// Process an individual request.
+        /// </summary>
+        /// <param name="context">The context for the current request.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public virtual async Task Invoke([NotNull] HttpContext context)
         {
             Check.NotNull(context, "context");

src/Microsoft.AspNet.Diagnostics.Entity/MigrationsEndPointOptions.cs

@@ -5,10 +5,20 @@ using Microsoft.AspNet.Http;
 
 namespace Microsoft.AspNet.Diagnostics.Entity
 {
+    /// <summary>
+    /// Options for the <see cref="MigrationsEndPointMiddleware"/>.
+    /// </summary>
     public class MigrationsEndPointOptions
     {
+        /// <summary>
+        /// The default value for <see cref="Path"/>.
+        /// </summary>
         public static PathString DefaultPath = new PathString("/ApplyDatabaseMigrations");
 
+        /// <summary>
+        /// Gets or sets the path that the <see cref="MigrationsEndPointMiddleware"/> will listen
+        /// for requests to execute migrations commands.
+        /// </summary>
         public virtual PathString Path { get; set; } = DefaultPath;
     }
 }