Update HostEnvironmentEnvExtensions.xml

Author: analogrelay

xml/Microsoft.Extensions.Hosting/HostEnvironmentEnvExtensions.xml

@@ -40,10 +40,13 @@
       </Parameters>
       <Docs>
         <param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
-        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />.</summary>
+        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />. This API should not be used in libraries, see remarks for details.</summary>
         <returns>
           <see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
+          authors should avoid coupling specific behavior to these environment names.
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IsEnvironment">
@@ -69,10 +72,13 @@
       <Docs>
         <param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
         <param name="environmentName">Environment name to validate against.</param>
-        <summary>Compares the current host environment name against the specified value.</summary>
+        <summary>Compares the current host environment name against the specified value. Library authors should avoid using this API, see remarks for details.</summary>
         <returns>
           <see langword="true" /> if the specified name is the same as the current environment; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          Environment names are generally specific to an application. Libraries designed for use in many different applications
+          should avoid coupling behavior to specific environment names.
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IsProduction">
@@ -96,10 +102,13 @@
       </Parameters>
       <Docs>
         <param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
-        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />.</summary>
+        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />. This API should not be used in libraries, see remarks for details.</summary>
         <returns>
           <see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
+          authors should avoid coupling specific behavior to these environment names.
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IsStaging">
@@ -123,10 +132,13 @@
       </Parameters>
       <Docs>
         <param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
-        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />.</summary>
+        <summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />. This API should not be used in libraries, see remarks for details.</summary>
         <returns>
           <see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
+          authors should avoid coupling specific behavior to these environment names.
+        </remarks>
       </Docs>
     </Member>
   </Members>