Add and update `///` comments to help consumers of these APIs (#51629)

* Added some API comments to help consumers have a better understanding of the order of operations, added unit tests, fixed redundancy in comment

* Update test to call UseEnv more than once directly

src/libraries/Microsoft.Extensions.Hosting.Abstractions/src/HostingAbstractionsHostExtensions.cs

@@ -51,7 +51,8 @@ public static void Run(this IHost host)
         }
 
         /// <summary>
-        /// Runs an application and returns a Task that only completes when the token is triggered or shutdown is triggered.
+        /// Runs an application and returns a <see cref="Task"/> that only completes when the token is triggered or shutdown is triggered.
+        /// The <paramref name="host"/> instance is disposed of after running.
         /// </summary>
         /// <param name="host">The <see cref="IHost"/> to run.</param>
         /// <param name="token">The token to trigger shutdown.</param>
@@ -74,7 +75,6 @@ public static async Task RunAsync(this IHost host, CancellationToken token = def
                 {
                     host.Dispose();
                 }
-
             }
         }
 

src/libraries/Microsoft.Extensions.Hosting.Abstractions/src/IHostEnvironment.cs

@@ -13,7 +13,7 @@ public interface IHostEnvironment
     {
         /// <summary>
         /// Gets or sets the name of the environment. The host automatically sets this property to the value of the
-        /// of the "environment" key as specified in configuration.
+        /// "environment" key as specified in configuration.
         /// </summary>
         string EnvironmentName { get; set; }
 

src/libraries/Microsoft.Extensions.Hosting/src/HostingHostBuilderExtensions.cs

@@ -19,7 +19,8 @@ namespace Microsoft.Extensions.Hosting
     public static class HostingHostBuilderExtensions
     {
         /// <summary>
-        /// Specify the environment to be used by the host.
+        /// Specify the environment to be used by the host. To avoid the environment being overwritten by a default
+        /// value, ensure this is called after defaults are configured.
         /// </summary>
         /// <param name="hostBuilder">The <see cref="IHostBuilder"/> to configure.</param>
         /// <param name="environment">The environment to host the application in.</param>
@@ -31,13 +32,14 @@ public static IHostBuilder UseEnvironment(this IHostBuilder hostBuilder, string
                 configBuilder.AddInMemoryCollection(new[]
                 {
                     new KeyValuePair<string, string>(HostDefaults.EnvironmentKey,
-                        environment  ?? throw new ArgumentNullException(nameof(environment)))
+                        environment ?? throw new ArgumentNullException(nameof(environment)))
                 });
             });
         }
 
         /// <summary>
-        /// Specify the content root directory to be used by the host.
+        /// Specify the content root directory to be used by the host. To avoid the content root directory being
+        /// overwritten by a default value, ensure this is called after defaults are configured.
         /// </summary>
         /// <param name="hostBuilder">The <see cref="IHostBuilder"/> to configure.</param>
         /// <param name="contentRoot">Path to root directory of the application.</param>
@@ -164,7 +166,8 @@ public static IHostBuilder ConfigureContainer<TContainerBuilder>(this IHostBuild
         }
 
         /// <summary>
-        /// Configures an existing <see cref="IHostBuilder"/> instance with pre-configured defaults.
+        /// Configures an existing <see cref="IHostBuilder"/> instance with pre-configured defaults. This will overwrite
+        /// previously configured values and is intended to be called before additional configuration calls.
         /// </summary>
         /// <remarks>
         ///   The following defaults are applied to the <see cref="IHostBuilder"/>:

src/libraries/Microsoft.Extensions.Hosting/tests/UnitTests/HostTests.cs

@@ -141,6 +141,49 @@ public void CreateDefaultBuilder_EnablesValidateOnBuild()
             Assert.Throws<AggregateException>(() => hostBuilder.Build());
         }
 
+        [Theory]
+        [InlineData("Beta-Testing"), InlineData("Another-Random-Env")]
+        public void UseEnvironmentIsOverwrittenByAdditionalCalls(string environment)
+        {
+            var expectedEnvironment = "SomeOtherEnvironment";
+            using var host = new HostBuilder()
+                .UseEnvironment(environment)
+                .ConfigureHostConfiguration(configBuilder =>
+                {
+                    configBuilder.AddInMemoryCollection(new[]
+                    {
+                        new KeyValuePair<string, string>(
+                            HostDefaults.EnvironmentKey, expectedEnvironment)
+                    });
+                }) // This overwrites the call to UseEnvironment
+                .Build();
+
+            var hostEnv = host.Services.GetRequiredService<IHostEnvironment>();
+            Assert.Equal(expectedEnvironment, hostEnv.EnvironmentName);
+        }
+
+        [Theory]
+        [InlineData("Beta-Testing"), InlineData("Another-Random-Env")]
+        public void LastCallToUseEnvironmentWins(string environment)
+        {
+            var willBeOverwritten = "SomeOtherEnvironment";
+            using var host = new HostBuilder()
+                .ConfigureHostConfiguration(configBuilder =>
+                {
+                    configBuilder.AddInMemoryCollection(new[]
+                    {
+                        new KeyValuePair<string, string>(
+                            HostDefaults.EnvironmentKey, willBeOverwritten)
+                    });
+                })
+                .UseEnvironment(Guid.NewGuid().ToString())
+                .UseEnvironment(environment) // Last one wins...
+                .Build();
+
+            var hostEnv = host.Services.GetRequiredService<IHostEnvironment>();
+            Assert.Equal(environment, hostEnv.EnvironmentName);
+        }
+
         [ConditionalFact(typeof(PlatformDetection), nameof(PlatformDetection.IsThreadingSupported))]
         [ActiveIssue("https://github.com/dotnet/runtime/issues/34582", TestPlatforms.Windows, TargetFrameworkMonikers.Netcoreapp, TestRuntimes.Mono)]
         [ActiveIssue("https://github.com/dotnet/runtime/issues/48696")]