Merge pull request #9795 from terrajobst/link-preview-apis

Provide more details for marking APIs as preview

Author: Immo Landwerth

xml/System.Diagnostics.CodeAnalysis/ExperimentalAttribute.xml

@@ -30,7 +30,13 @@
   </Attributes>
   <Docs>
     <summary>Indicates that an API is experimental and it may change in the future.</summary>
-    <remarks>This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental feature is used. Authors can use this attribute to ship preview features in their assemblies.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+<xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute> allows call sites to be flagged with a diagnostic that indicates that an experimental feature is used. You can use this attribute to ship preview features in otherwise stable libraries.
+
+For more information about marking APIs as preview, see [Preview APIs](/dotnet/fundamentals/apicompat/preview-apis).
+      ]]></format>
+    </remarks>
     <seealso cref="T:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute" />
   </Docs>
   <Members>

xml/System.Runtime.Versioning/RequiresPreviewFeaturesAttribute.xml

@@ -32,7 +32,15 @@
   </Attributes>
   <Docs>
     <summary>Indicates that an API is in preview. This attribute allows call sites to be flagged with a diagnostic that indicates that a preview feature is used. Authors can use this attribute to ship preview features in their assemblies.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+<xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute> marks an API as requiring preview functionality from the .NET runtime, its core libraries, and the compilers. This API is intended for platform-provided functionality and generally shouldn't be used in user code.
+
+If you want to ship preview functionality in your own libraries, use <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute> instead.
+
+For more information about marking APIs as preview, see [Preview APIs](/dotnet/fundamentals/apicompat/preview-apis).
+      ]]></format>
+    </remarks>
     <related type="Article" href="https://aka.ms/dotnet-warnings/preview-features">Preview Features</related>
   </Docs>
   <Members>