Merge pull request #11459 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml

@@ -31,9 +31,15 @@
         corresponds to the feature switch specified by name.</para>
     </summary>
     <remarks>
-      <para>
-        IL rewriters and compilers can use this attribute to substitute the return value
-        of the specified property with the value of the feature switch.</para>
+      <format type="text/markdown"><![CDATA[
+IL rewriters and compilers can use this attribute to substitute the return value of the specified property with the value of the feature switch.
+
+The value of the feature switch can only be specified at the application level and affects the entire application. It is possible to get into situations where one library that is part of the application requires the feature switch to be turned on, but has no way to communicate this to the application author.
+
+Feature switches complicate unit testing and code sharing since different application configurations might have different values of the feature switch, and it's difficult to ensure all code paths work as expected.
+
+It is therefore preferable to structure APIs in a way that trimming can happen naturally without any feature switches. The use of feature switches should be reserved for situations where trimming needs to happen, but it's not feasible to change the APIs to allow trimming naturally.
+ ]]></format>
     </remarks>
     <example>
       <format type="text/markdown"><![CDATA[
@@ -55,10 +61,9 @@ When the app is trimmed with the following feature settings in the project file,
 
 ```xml
 <ItemGroup>
-  <RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" />
+  <RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" Trim="true" />
 </ItemGroup>
 ```
-
 ]]></format>
     </example>
   </Docs>

xml/System.Diagnostics/ProcessStartInfo.xml

@@ -645,7 +645,7 @@ If you use this property to set command-line arguments, <xref:System.Diagnostics
       </ReturnValue>
       <Docs>
         <summary>Gets the environment variables that apply to this process and its child processes.</summary>
-        <value>A generic dictionary containing the environment variables that apply to this process and its child processes. The default is <see langword="null" />.</value>
+        <value>A generic dictionary containing the environment variables that apply to this process and its child processes.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -728,7 +728,7 @@ If you use this property to set command-line arguments, <xref:System.Diagnostics
       </ReturnValue>
       <Docs>
         <summary>Gets search paths for files, directories for temporary files, application-specific options, and other similar information.</summary>
-        <value>A string dictionary that provides environment variables that apply to this process and child processes. The default is <see langword="null" />.</value>
+        <value>A string dictionary that provides environment variables that apply to this process and child processes.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[