Add doc strings for public APIs in src/Hosting (#26443)

* Add doc strings for public APIs in src/Hosting

* Apply suggestions from code review

Co-authored-by: Chris Ross <Tratcher@Outlook.com>
Co-authored-by: Pranav K <prkrishn@hotmail.com>
Co-authored-by: James Newton-King <james@newtonking.com>

* Address feedback from peer review

Co-authored-by: Chris Ross <Tratcher@Outlook.com>
Co-authored-by: Pranav K <prkrishn@hotmail.com>
Co-authored-by: James Newton-King <james@newtonking.com>

Author: 4 people

src/Hosting/Abstractions/src/EnvironmentName.cs

@@ -9,8 +9,19 @@ namespace Microsoft.AspNetCore.Hosting
     [System.Obsolete("This type is obsolete and will be removed in a future version. The recommended alternative is Microsoft.Extensions.Hosting.Environments.", error: false)]
     public static class EnvironmentName
     {
+        /// <summary>
+        /// A string constant for Development environments.
+        /// </summary>
         public static readonly string Development = "Development";
+
+        /// <summary>
+        /// A string constant for Staging environments.
+        /// </summary>
         public static readonly string Staging = "Staging";
+
+        /// <summary>
+        /// A string constant for Production environments.
+        /// </summary>
         public static readonly string Production = "Production";
     }
 }

src/Hosting/Abstractions/src/HostingAbstractionsWebHostBuilderExtensions.cs

@@ -12,6 +12,9 @@
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Contains extension methods for configuring the <see cref="IWebHostBuilder" />.
+    /// </summary>
     public static class HostingAbstractionsWebHostBuilderExtensions
     {
         /// <summary>

src/Hosting/Abstractions/src/IStartup.cs

@@ -7,10 +7,21 @@
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Provides an interface for initializing services and middleware used by an application.
+    /// </summary>
     public interface IStartup
     {
+        /// <summary>
+        /// Register services into the <see cref="IServiceCollection" />.
+        /// </summary>
+        /// <param name="services">The <see cref="IServiceCollection"/> to add the services to.</param>
         IServiceProvider ConfigureServices(IServiceCollection services);
 
+        /// <summary>
+        /// Configures the application.
+        /// </summary>
+        /// <param name="app">An <see cref="IApplicationBuilder"/> for the app to configure.</param>
         void Configure(IApplicationBuilder app);
     }
-}
+}

src/Hosting/Abstractions/src/IStartupConfigureContainerFilter.cs

@@ -12,6 +12,11 @@ namespace Microsoft.AspNetCore.Hosting
     [Obsolete]
     public interface IStartupConfigureContainerFilter<TContainerBuilder>
     {
+        /// <summary>
+        /// Extends the provided <paramref name="container"/> and returns a modified <see cref="Action"/> action of the same type.
+        /// </summary>
+        /// <param name="container">The ConfigureContainer method to extend.</param>
+        /// <returns>A modified <see cref="Action"/>.</returns>
         Action<TContainerBuilder> ConfigureContainer(Action<TContainerBuilder> container);
     }
 }

src/Hosting/Abstractions/src/IStartupConfigureServicesFilter.cs

@@ -13,6 +13,11 @@ namespace Microsoft.AspNetCore.Hosting
     [Obsolete]
     public interface IStartupConfigureServicesFilter
     {
+        /// <summary>
+        /// Extends the provided <paramref name="next"/> and returns a modified <see cref="Action"/> action of the same type.
+        /// </summary>
+        /// <param name="next">The ConfigureServices method to extend.</param>
+        /// <returns>A modified <see cref="Action"/>.</returns>
         Action<IServiceCollection> ConfigureServices(Action<IServiceCollection> next);
     }
 }

src/Hosting/Abstractions/src/IStartupFilter.cs

@@ -6,8 +6,19 @@
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Provides an interface for extending the middleware pipeline with new
+    /// Configure methods. Can be used to add defaults to the beginning or
+    /// end of the pipeline without having to make the app author explicitly
+    /// register middleware.
+    /// </summary>
     public interface IStartupFilter
     {
+        /// <summary>
+        /// Extends the provided <paramref name="next"/> and returns an <see cref="Action"/> of the same type.
+        /// </summary>
+        /// <param name="next">The Configure method to extend.</param>
+        /// <returns>A modified <see cref="Action"/>.</returns>
         Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next);
     }
 }

src/Hosting/Abstractions/src/Microsoft.AspNetCore.Hosting.Abstractions.csproj

@@ -4,7 +4,7 @@
     <Description>ASP.NET Core hosting and startup abstractions for web applications.</Description>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
     <IsAspNetCoreApp>true</IsAspNetCoreApp>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn.Replace('1591', ''))</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageTags>aspnetcore;hosting</PackageTags>
     <IsPackable>false</IsPackable>

src/Hosting/Abstractions/src/WebHostDefaults.cs

@@ -3,24 +3,85 @@
 
 namespace Microsoft.AspNetCore.Hosting
 {
+    /// <summary>
+    /// Contains a set of constants representing configuration keys.
+    /// </summary>
     public static class WebHostDefaults
     {
+        /// <summary>
+        /// The configuration key associated with an application name.
+        /// </summary>
         public static readonly string ApplicationKey = "applicationName";
+
+        /// <summary>
+        /// The configuration key associated with the startup assembly.
+        /// </summary>
         public static readonly string StartupAssemblyKey = "startupAssembly";
+
+        /// <summary>
+        /// The configuration key associated with "hostingStartupAssemblies" configuration.
+        /// </summary>
         public static readonly string HostingStartupAssembliesKey = "hostingStartupAssemblies";
+
+        /// <summary>
+        /// The configuration key associated with the "hostingStartupExcludeAssemblies" configuration.
+        /// </summary>
         public static readonly string HostingStartupExcludeAssembliesKey = "hostingStartupExcludeAssemblies";
 
+        /// <summary>
+        /// The configuration key associated with the "DetailedErrors" configuration.
+        /// </summary>
+
         public static readonly string DetailedErrorsKey = "detailedErrors";
+
+        /// <summary>
+        /// The configuration key associated with the application's environment setting.
+        /// </summary>
         public static readonly string EnvironmentKey = "environment";
+
+        /// <summary>
+        /// The configuration key associated with the "webRoot" configuration.
+        /// </summary>
         public static readonly string WebRootKey = "webroot";
+
+        /// <summary>
+        /// The configuration key associated with the "captureStartupErrors" configuration.
+        /// </summary>
         public static readonly string CaptureStartupErrorsKey = "captureStartupErrors";
+
+        /// <summary>
+        /// The configuration key associated with the "urls" configuration.
+        /// </summary>
         public static readonly string ServerUrlsKey = "urls";
+
+        /// <summary>
+        /// The configuration key associated with the "ContentRoot" configuration.
+        /// </summary>
         public static readonly string ContentRootKey = "contentRoot";
+
+        /// <summary>
+        /// The configuration key associated with the "PreferHostingUrls" configuration.
+        /// </summary>
         public static readonly string PreferHostingUrlsKey = "preferHostingUrls";
+
+        /// <summary>
+        /// The configuration key associated with the "PreventHostingStartup" configuration.
+        /// </summary>
         public static readonly string PreventHostingStartupKey = "preventHostingStartup";
+
+        /// <summary>
+        /// The configuration key associated with the "SuppressStatusMessages" configuration.
+        /// </summary>
         public static readonly string SuppressStatusMessagesKey = "suppressStatusMessages";
 
+        /// <summary>
+        /// The configuration key associated with the "ShutdownTimeoutSeconds" configuration.
+        /// </summary>
         public static readonly string ShutdownTimeoutKey = "shutdownTimeoutSeconds";
+
+        /// <summary>
+        /// The configuration key associated with the "StaticWebAssets" configuration.
+        /// </summary>
         public static readonly string StaticWebAssetsKey = "staticWebAssets";
     }
 }

src/Hosting/Hosting/src/Builder/ApplicationBuilderFactory.cs

@@ -9,15 +9,27 @@
 
 namespace Microsoft.AspNetCore.Hosting.Builder
 {
+    /// <summary>
+    /// A factory for creating <see cref="IApplicationBuilder" /> instances.
+    /// </summary>
     public class ApplicationBuilderFactory : IApplicationBuilderFactory
     {
         private readonly IServiceProvider _serviceProvider;
 
+        /// <summary>
+        /// Initialize a new factory instance with an <see cref="IServiceProvider" />.
+        /// </summary>
+        /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to resolve dependencies and initialize components.</param>
         public ApplicationBuilderFactory(IServiceProvider serviceProvider)
         {
             _serviceProvider = serviceProvider;
         }
 
+        /// <summary>
+        /// Create an <see cref="IApplicationBuilder" /> builder given a <paramref name="serverFeatures" />.
+        /// </summary>
+        /// <param name="serverFeatures">An <see cref="IFeatureCollection"/> of HTTP features.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/> configured with <paramref name="serverFeatures"/>.</returns>
         public IApplicationBuilder CreateBuilder(IFeatureCollection serverFeatures)
         {
             return new ApplicationBuilder(_serviceProvider, serverFeatures);

src/Hosting/Hosting/src/Builder/IApplicationBuilderFactory.cs

@@ -6,8 +6,16 @@
 
 namespace Microsoft.AspNetCore.Hosting.Builder
 {
+    /// <summary>
+    /// Provides an interface for implementing a factory that produces <see cref="IApplicationBuilder"/> instances.
+    /// </summary>
     public interface IApplicationBuilderFactory
     {
+        /// <summary>
+        /// Create an <see cref="IApplicationBuilder" /> builder given a <paramref name="serverFeatures" />
+        /// </summary>
+        /// <param name="serverFeatures">An <see cref="IFeatureCollection"/> of HTTP features.</param>
+        /// <returns>An <see cref="IApplicationBuilder"/> configured with <paramref name="serverFeatures"/>.</returns>
         IApplicationBuilder CreateBuilder(IFeatureCollection serverFeatures);
     }
-}
+}