Fix example formatting (dotnet#5218)

Author: gewarren

xml/Microsoft.Extensions.Http/PolicyHttpMessageHandler.xml

@@ -18,60 +18,33 @@
   <Docs>
     <summary>A <see cref="T:System.Net.Http.DelegatingHandler" /> implementation that executes request processing surrounded by a <see cref="T:Polly.Policy" />.</summary>
     <remarks>
-      <para>
-            This message handler implementation supports the use of policies provided by the Polly library for 
-            transient-fault-handling and resiliency.
-            </para>
-      <para>
-            The documentation provided here is focused guidance for using Polly together with the <see cref="T:System.Net.Http.IHttpClientFactory" />. 
-            See the Polly project and its documentation (https://github.com/app-vnext/Polly) for authoritative information on Polly.
-            </para>
-      <para>
-            The extension methods on <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions" /> are designed as a convenient and correct
-            way to create a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler" />.
-            </para>
-      <para>
-            The <see cref="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})" />
-            method supports the creation of a <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler" /> for any kind of policy. This includes
-            non-reactive policies, such as Timeout or Cache, which don't require the underlying request to fail first.
-            </para>
-      <para>
-        <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler" /> and the <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions" /> convenience methods
-            only accept the generic <see cref="T:Polly.IAsyncPolicy`1" />. Generic policy instances can be created
-            by using the generic methods on <see cref="T:Polly.Policy" /> such as <see cref="M:Polly.Policy.TimeoutAsync``1(System.Int32)" />.
-            </para>
-      <para>
-            To adapt an existing non-generic <see cref="T:Polly.IAsyncPolicy" />, use code like the following:
-            <example>
-            Converting a non-generic <c>IAsyncPolicy policy</c> to <see cref="T:Polly.IAsyncPolicy`1" />.
-            <code>
-            policy.AsAsyncPolicy&lt;HttpResponseMessage&gt;()
-            </code></example></para>
-      <para>
-            The <see cref="M:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddTransientHttpErrorPolicy(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{Polly.PolicyBuilder{System.Net.Http.HttpResponseMessage},Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})" />
-            method is an opinionated convenience method that supports the application of a policy for requests that fail due
-            to a connection failure or server error (5XX HTTP status code). This kind of method supports only reactive policies
-            such as Retry, Circuit-Breaker or Fallback. This method is only provided for convenience; we recommend creating
-            your own policies as needed if this does not meet your requirements.
-            </para>
-      <para>
-            Take care when using policies such as Retry or Timeout together as HttpClient provides its own timeout via 
-            <see cref="P:System.Net.Http.HttpClient.Timeout" />.  When combining Retry and Timeout, <see cref="P:System.Net.Http.HttpClient.Timeout" /> will act as a
-            timeout across all tries; a Polly Timeout policy can be configured after a Retry policy in the configuration sequence,
-            to provide a timeout-per-try.
-            </para>
-      <para>
-            All policies provided by Polly are designed to be efficient when used in a long-lived way. Certain policies such as the 
-            Bulkhead and Circuit-Breaker maintain state and should be scoped across calls you wish to share the Bulkhead or Circuit-Breaker state. 
-            Take care to ensure the correct lifetimes when using policies and message handlers together in custom scenarios. The extension
-            methods provided by <see cref="T:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions" /> are designed to assign a long lifetime to policies
-            and ensure that they can be used when the handler rotation feature is active.
-            </para>
-      <para>
-            The <see cref="T:Microsoft.Extensions.Http.PolicyHttpMessageHandler" /> will attach a context to the <see cref="T:System.Net.Http.HttpRequestMessage" /> prior
-            to executing a <see cref="T:Polly.Policy" />, if one does not already exist. The <see cref="T:Polly.Context" /> will be provided
-            to the policy for use inside the <see cref="T:Polly.Policy" /> and in other message handlers.
-            </para>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+This message handler implementation supports the use of policies provided by the Polly library for transient-fault-handling and resiliency.
+
+The documentation provided here is focused guidance for using Polly together with the <xref:System.Net.Http.IHttpClientFactory>. See the Polly project and [its documentation](https://github.com/app-vnext/Polly) for authoritative information on Polly.
+
+The extension methods on <xref:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions> are designed as a convenient and correct way to create a <xref:Microsoft.Extensions.Http.PolicyHttpMessageHandler>.
+
+The <xref:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddPolicyHandler(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage})> method supports the creation of a <xref:Microsoft.Extensions.Http.PolicyHttpMessageHandler> for any kind of policy. This includes non-reactive policies, such as Timeout or Cache, which don't require the underlying request to fail first.
+
+<xref:Microsoft.Extensions.Http.PolicyHttpMessageHandler> and the <xref:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions> convenience methods only accept the generic <xref:Polly.IAsyncPolicy`1>. Generic policy instances can be created by using the generic methods on <xref:Polly.Policy> such as <xref:Polly.Policy.TimeoutAsync``1(System.Int32)>.
+
+To adapt an existing non-generic <xref:Polly.IAsyncPolicy>, use code like the following:
+        
+```
+policy.AsAsyncPolicy&lt;HttpResponseMessage&gt;()
+```
+
+The <xref:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions.AddTransientHttpErrorPolicy(Microsoft.Extensions.DependencyInjection.IHttpClientBuilder,System.Func{Polly.PolicyBuilder{System.Net.Http.HttpResponseMessage},Polly.IAsyncPolicy{System.Net.Http.HttpResponseMessage}})> method is an opinionated convenience method that supports the application of a policy for requests that fail due to a connection failure or server error (5XX HTTP status code). This kind of method supports only reactive policies such as Retry, Circuit-Breaker or Fallback. This method is only provided for convenience; we recommend creating your own policies as needed if this does not meet your requirements.
+
+Take care when using policies such as Retry or Timeout together, as HttpClient provides its own timeout via <xref:System.Net.Http.HttpClient.Timeout>. When combining Retry and Timeout, <xref:System.Net.Http.HttpClient.Timeout> will act as a timeout across all tries; a Polly Timeout policy can be configured after a Retry policy in the configuration sequence, to provide a timeout-per-try.
+
+All policies provided by Polly are designed to be efficient when used in a long-lived way. Certain policies such as the Bulkhead and Circuit-Breaker maintain state and should be scoped across calls you wish to share the Bulkhead or Circuit-Breaker state. Take care to ensure the correct lifetimes when using policies and message handlers together in custom scenarios. The extension methods provided by <xref:Microsoft.Extensions.DependencyInjection.PollyHttpClientBuilderExtensions> are designed to assign a long lifetime to policies and ensure that they can be used when the handler rotation feature is active.
+
+The <xref:Microsoft.Extensions.Http.PolicyHttpMessageHandler> will attach a context to the <xref:System.Net.Http.HttpRequestMessage> prior to executing a <xref:Polly.Policy>, if one does not already exist. The <xref:Polly.Context> will be provided to the policy for use inside the <xref:Polly.Policy> and in other message handlers.
+   ]]></format>
     </remarks>
   </Docs>
   <Members>