[Doc Comment Translation] Improve Remarks Formatting

[jsquire]

Summary

The focus of these changes is to improve formatting for the <remarks> element of the XML doc comments to treat them as text rather than pre-formatted blocks.

Previously, transformation was sensitive to the formatting of the source code, attempting to preserve line breaks and spacing rather than treating it as XML content. The source code was often formatted to wrap lines so that they could be more easily read by other developers, causing the rendering for the MS Docs site to contain awkward and undesirable formatting.

With these changes, the <remarks> are treated as content, normalizing line breaks and spacing and introducing explicit paragraphs to ensure that the structure is semantically accurate and assist in HTML rendering.

This should address the asks in DevOps #136807 and #373096. It should also address the other remarks formatting issues that have been reported to the Azure SDK repository, such as the EventDataBatch::TryAdd member:

References and Related

• Azure DevOps #136807 (Microsoft Internal)
• Azure DevOps #373096 (Microsoft Internal)
• [Service Bus] Docs remarks layout is Incorrect (#18783)
• Markup mistake in Remarks section #18025
• [DOCS] Remarks have strange formatting in API docs for keyclient.getkeyasync (#13567)

[jsquire]

//cc: @DanielJurek, @AlexGhiondea, @TianqiZhang

[TianqiZhang]

This change could potentially fix AB#136807.