From b2289b3356b8389d93bcef14fd380b75265e7b68 Mon Sep 17 00:00:00 2001
From: Tom Vervoort <tomv@infosupport.com>
Date: Fri, 28 Oct 2022 11:48:55 +0200
Subject: [PATCH] improve xml docs of some hard to read lists

---
 .../Internal/JsonTranscodingRouteAdapter.cs   | 24 ++++++++++-----
 .../src/IHttpRequestBodyDetectionFeature.cs   | 29 ++++++++++++++-----
 2 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/src/Grpc/JsonTranscoding/src/Microsoft.AspNetCore.Grpc.JsonTranscoding/Internal/JsonTranscodingRouteAdapter.cs b/src/Grpc/JsonTranscoding/src/Microsoft.AspNetCore.Grpc.JsonTranscoding/Internal/JsonTranscodingRouteAdapter.cs
index 76a00c8757eb..a65ed0fcade6 100644
--- a/src/Grpc/JsonTranscoding/src/Microsoft.AspNetCore.Grpc.JsonTranscoding/Internal/JsonTranscodingRouteAdapter.cs
+++ b/src/Grpc/JsonTranscoding/src/Microsoft.AspNetCore.Grpc.JsonTranscoding/Internal/JsonTranscodingRouteAdapter.cs
@@ -10,24 +10,32 @@ namespace Microsoft.AspNetCore.Grpc.JsonTranscoding.Internal;
 
 /// <summary>
 /// Routes on HTTP rule are similar to ASP.NET Core routes but add and remove some features.
-/// - Constraints aren't supported.
-/// - Optional parameters aren't supported.
-/// - Parameters spanning multiple segments are supported.
+/// <list type="bullet">
+/// <item><description>Constraints aren't supported.</description></item>
+/// <item><description>Optional parameters aren't supported.</description></item>
+/// <item><description>Parameters spanning multiple segments are supported.</description></item>
+/// </list>
 ///
 /// The purpose of this type is to add support for parameters spanning multiple segments and
 /// anonymous any or catch-all segments. This type transforms an HTTP route into an ASP.NET Core
 /// route by rewritting it to a compatible format and providing actions to reconstruct parameters
 /// that span multiple segments.
 ///
+/// <para>
 /// For example, consider a multi-segment parameter route:
-/// - Before: /v1/{book.name=shelves/*/books/*}
-/// - After: /v1/shelves/{__Complex_book.name_2}/books/{__Complex_book.name_4}
-///
+/// <list type="bullet">
+/// <item><description>Before: /v1/{book.name=shelves/*/books/*}</description></item>
+/// <item><description>After: /v1/shelves/{__Complex_book.name_2}/books/{__Complex_book.name_4}</description></item>
+/// </list>
+/// </para>
+/// 
 /// It is rewritten so that any * or ** segments become ASP.NET Core route parameters. These parameter
 /// names are never used by the user, and instead they're reconstructed into the final value by the
 /// adapter and then added to the HttpRequest.RouteValues collection.
-/// - Request URL: /v1/shelves/example-shelf/books/example-book
-/// - Route parameter: book.name = shelves/example-self/books/example-book
+/// <list type="bullet">
+/// <item><description>Request URL: /v1/shelves/example-shelf/books/example-book</description></item>
+/// <item><description>Route parameter: book.name = shelves/example-self/books/example-book</description></item>
+/// </list>
 /// </summary>
 internal sealed class JsonTranscodingRouteAdapter
 {
diff --git a/src/Http/Http.Features/src/IHttpRequestBodyDetectionFeature.cs b/src/Http/Http.Features/src/IHttpRequestBodyDetectionFeature.cs
index 7d9d64c3fd16..0e02daa33063 100644
--- a/src/Http/Http.Features/src/IHttpRequestBodyDetectionFeature.cs
+++ b/src/Http/Http.Features/src/IHttpRequestBodyDetectionFeature.cs
@@ -13,15 +13,30 @@ public interface IHttpRequestBodyDetectionFeature
     /// </summary>
     /// <remarks>
     /// This returns true when:
-    /// - It's an HTTP/1.x request with a non-zero Content-Length or a 'Transfer-Encoding: chunked' header.
-    /// - It's an HTTP/2 request that did not set the END_STREAM flag on the initial headers frame.
+    /// <list type="bullet">
+    /// <item><description>
+    /// It's an HTTP/1.x request with a non-zero Content-Length or a 'Transfer-Encoding: chunked' header.
+    /// </description></item>
+    /// <item><description>
+    /// It's an HTTP/2 request that did not set the END_STREAM flag on the initial headers frame.
+    /// </description></item>
+    /// </list>
     /// The final request body length may still be zero for the chunked or HTTP/2 scenarios.
-    ///
+    /// <para>
     /// This returns false when:
-    /// - It's an HTTP/1.x request with no Content-Length or 'Transfer-Encoding: chunked' header, or the Content-Length is 0.
-    /// - It's an HTTP/1.x request with Connection: Upgrade (e.g. WebSockets). There is no HTTP request body for these requests and
-    ///   no data should be received until after the upgrade.
-    /// - It's an HTTP/2 request that set END_STREAM on the initial headers frame.
+    /// <list type="bullet">
+    /// <item><description>
+    /// It's an HTTP/1.x request with no Content-Length or 'Transfer-Encoding: chunked' header, or the Content-Length is 0.
+    /// </description></item>
+    /// <item><description>
+    /// It's an HTTP/1.x request with Connection: Upgrade (e.g. WebSockets). There is no HTTP request body for these requests and
+    /// no data should be received until after the upgrade.
+    /// </description></item>
+    /// <item><description>
+    /// It's an HTTP/2 request that set END_STREAM on the initial headers frame.
+    /// </description></item>
+    /// </list>
+    /// </para>
     /// When false, the request body should never return data.
     /// </remarks>
     bool CanHaveBody { get; }