Add examples to Feature attributes

Author: sbomer

xml/System.Diagnostics.CodeAnalysis/FeatureGuardAttribute.xml

@@ -29,14 +29,35 @@
   </Attributes>
   <Docs>
     <summary>
-      <para>Indicates that the specified public static boolean get-only property</para>
-      <para>guards access to the specified feature.</para>
+      <para>
+        Indicates that the specified public static boolean get-only property
+        guards access to the specified feature.</para>
     </summary>
     <remarks>
-      <para>Analyzers can use this to prevent warnings on calls to code that is</para>
-      <para>annotated as requiring that feature, when the callsite is guarded by a</para>
-      <para>call to the property.</para>
+      <para>
+        Analyzers can use this to prevent warnings on calls to code that is
+        annotated as requiring that feature, when the callsite is guarded by a
+        call to the property.</para>
     </remarks>
+    <example>
+      <code language="csharp">
+          if (Feature.IsSupported)
+              Feature.Implementation();
+
+          public class Feature
+          {
+              [FeatureGuard(typeof(RequiresDynamicCodeAttribute))]
+              internal static bool IsSupported => RuntimeFeature.IsDynamicCodeSupported;
+
+              [RequiresDynamicCode("Feature requires dynamic code support.")]
+              internal static Implementation() => ...; // Uses dynamic code
+          }
+      </code>
+      When the app is built with `&ltPublishAot&gt;true&lt/PublishAot&gt;`, the call to
+      `Feature.Implementation()` doesn't produce analyzer warning
+      <see href="https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/warnings/il3050">IL3050</see>,
+      and `Feature.Implementation` code is removed when publishing.
+    </example>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml

@@ -29,13 +29,36 @@
   </Attributes>
   <Docs>
     <summary>
-      <para>Indicates that the specified public static boolean get-only property</para>
-      <para>corresponds to the feature switch specified by name.</para>
+      <para>
+        Indicates that the specified public static boolean get-only property
+        corresponds to the feature switch specified by name.</para>
     </summary>
     <remarks>
-      <para>IL rewriters and compilers can use this to substitute the return value</para>
-      <para>of the specified property with the value of the feature switch.</para>
+      <para>
+        IL rewriters and compilers can use this to substitute the return value
+        of the specified property with the value of the feature switch.</para>
     </remarks>
+    <example>
+      <code language="csharp">
+          if (Feature.IsSupported)
+              Feature.Implementation();
+
+          public class Feature
+          {
+              [FeatureSwitchDefinition("Feature.IsSupported")]
+              internal static bool IsSupported => AppContext.TryGetSwitch("Feature.IsSupported", out bool isEnabled) ? isEnabled : true;
+
+              internal static Implementation() => ...;
+          }
+      </code>
+      When the app is trimmed with the following feature settings in the project file,
+      `Feature.IsSupported` is treated as `false`, and `Feature.Implementation` code is removed.
+      <code language="xml">
+        &lt;ItemGroup&gt;
+          &lt;RuntimeHostConfigurationOption Include="Feature.IsSupported" Value="false" /&gt;
+        &lt;/ItemGroup&gt;
+      </code>
+    </example>
   </Docs>
   <Members>
     <Member MemberName=".ctor">