Skip to content

Commit 26f18fa

Browse files
ericstjericstj
authored
Merge pull request #4204 from dotnet/anurse/ext-3054-doc-update
Update docs for IsNNN extension methods on IHost(ing)Environment
2 parents a5a9f59 + a114ec3 commit 26f18fa

File tree

2 files changed

+40
-16
lines changed

2 files changed

+40
-16
lines changed

‎xml/Microsoft.Extensions.Hosting/HostEnvironmentEnvExtensions.xml‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,13 @@
4040
</Parameters>
4141
<Docs>
4242
<param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
43-
<summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />.</summary>
43+
<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>
4444
<returns>
4545
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />; otherwise, <see langword="false" />.</returns>
46-
<remarks>To be added.</remarks>
46+
<remarks>
47+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
48+
authors should avoid coupling specific behavior to these environment names.
49+
</remarks>
4750
</Docs>
4851
</Member>
4952
<Member MemberName="IsEnvironment">
@@ -69,10 +72,13 @@
6972
<Docs>
7073
<param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
7174
<param name="environmentName">Environment name to validate against.</param>
72-
<summary>Compares the current host environment name against the specified value.</summary>
75+
<summary>Compares the current host environment name against the specified value. Library authors should avoid using this API, see remarks for details.</summary>
7376
<returns>
7477
<see langword="true" /> if the specified name is the same as the current environment; otherwise, <see langword="false" />.</returns>
75-
<remarks>To be added.</remarks>
78+
<remarks>
79+
Environment names are generally specific to an application. Libraries designed for use in many different applications
80+
should avoid coupling behavior to specific environment names.
81+
</remarks>
7682
</Docs>
7783
</Member>
7884
<Member MemberName="IsProduction">
@@ -96,10 +102,13 @@
96102
</Parameters>
97103
<Docs>
98104
<param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
99-
<summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />.</summary>
105+
<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>
100106
<returns>
101107
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />; otherwise, <see langword="false" />.</returns>
102-
<remarks>To be added.</remarks>
108+
<remarks>
109+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
110+
authors should avoid coupling specific behavior to these environment names.
111+
</remarks>
103112
</Docs>
104113
</Member>
105114
<Member MemberName="IsStaging">
@@ -123,10 +132,13 @@
123132
</Parameters>
124133
<Docs>
125134
<param name="hostEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostEnvironment" />.</param>
126-
<summary>Checks if the current host environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />.</summary>
135+
<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>
127136
<returns>
128137
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />; otherwise, <see langword="false" />.</returns>
129-
<remarks>To be added.</remarks>
138+
<remarks>
139+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
140+
authors should avoid coupling specific behavior to these environment names.
141+
</remarks>
130142
</Docs>
131143
</Member>
132144
</Members>

‎xml/Microsoft.Extensions.Hosting/HostingEnvironmentExtensions.xml‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,13 @@
4444
</Parameters>
4545
<Docs>
4646
<param name="hostingEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostingEnvironment" />.</param>
47-
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />.</summary>
47+
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />. This API should not be used in libraries, see remarks for details.</summary>
4848
<returns>
4949
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Development" />; otherwise, <see langword="false" />.</returns>
50-
<remarks>To be added.</remarks>
50+
<remarks>
51+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
52+
authors should avoid coupling specific behavior to these environment names.
53+
</remarks>
5154
</Docs>
5255
</Member>
5356
<Member MemberName="IsEnvironment">
@@ -75,10 +78,13 @@
7578
<Docs>
7679
<param name="hostingEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostingEnvironment" />.</param>
7780
<param name="environmentName">Environment name to validate against.</param>
78-
<summary>Compares the current hosting environment name against the specified value.</summary>
81+
<summary>Compares the current hosting environment name against the specified value. Library authors should avoid using this API, see remarks for details.</summary>
7982
<returns>
8083
<see langword="true" /> if the specified name is the same as the current environment; otherwise, <see langword="false" />.</returns>
81-
<remarks>To be added.</remarks>
84+
<remarks>
85+
Environment names are generally specific to an application. Libraries designed for use in many different applications
86+
should avoid coupling behavior to specific environment names.
87+
</remarks>
8288
</Docs>
8389
</Member>
8490
<Member MemberName="IsProduction">
@@ -104,10 +110,13 @@
104110
</Parameters>
105111
<Docs>
106112
<param name="hostingEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostingEnvironment" />.</param>
107-
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />.</summary>
113+
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />. This API should not be used in libraries, see remarks for details.</summary>
108114
<returns>
109115
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Production" />; otherwise, <see langword="false" />.</returns>
110-
<remarks>To be added.</remarks>
116+
<remarks>
117+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
118+
authors should avoid coupling specific behavior to these environment names.
119+
</remarks>
111120
</Docs>
112121
</Member>
113122
<Member MemberName="IsStaging">
@@ -133,10 +142,13 @@
133142
</Parameters>
134143
<Docs>
135144
<param name="hostingEnvironment">An instance of <see cref="T:Microsoft.Extensions.Hosting.IHostingEnvironment" />.</param>
136-
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />.</summary>
145+
<summary>Checks if the current hosting environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />. This API should not be used in libraries, see remarks for details.</summary>
137146
<returns>
138147
<see langword="true" /> if the environment name is <see cref="F:Microsoft.Extensions.Hosting.EnvironmentName.Staging" />; otherwise, <see langword="false" />.</returns>
139-
<remarks>To be added.</remarks>
148+
<remarks>
149+
The environment names "Development", "Production" and "Staging" are provided as a utility for application developers. Library
150+
authors should avoid coupling specific behavior to these environment names.
151+
</remarks>
140152
</Docs>
141153
</Member>
142154
</Members>

0 commit comments

Comments
 (0)