Fix more <para> cases (#173)

* Improve the logic that wraps paragraphs with <para></para>
- Join paragraphs separated by newlines.
- Split paragraphs that end in "." or ":".
- Treat "-or-" and "- or -" as their own paragraphs.
- Make sure single paragraphs are not wrapped.
- Make sure empty newlines are ignored.

* Tests

* Version bump.

Author: carlossanlop

src/PortToDocs/src/app/PortToDocs.csproj

@@ -7,7 +7,7 @@
     <Nullable>enable</Nullable>
     <IsPackable>true</IsPackable>
     <PackAsTool>true</PackAsTool>
-    <Version>1.4</Version>
+    <Version>1.5</Version>
   </PropertyGroup>
 
   <ItemGroup>

src/PortToDocs/src/libraries/XmlHelper.cs

@@ -203,19 +203,57 @@ public static string GetFormattedAsXml(string value, bool removeUndesiredEndline
         private static string ReplaceEndLinesWithParas(string updatedValue)
         {
             string[] splitted = updatedValue.Split(_splittingSeparators, _splittingStringSplitOptions);
-            bool moreThanOne = splitted.Count() > 1;
+
+            if (splitted.Length == 1)
+            {
+                // No need to add paras
+                return splitted[0];
+            }
 
             StringBuilder newValue = new();
-            foreach (string s in splitted)
+            ReadOnlySpan<char> ros;
+            bool addStartParaNext = true;
+            for (int i = 0; i < splitted.Length; i++)
             {
-                if (moreThanOne && !s.StartsWith("<para>"))
+                ros = splitted[i];
+
+                if (ros.StartsWith("<para>") && ros.EndsWith("</para>"))
                 {
-                    newValue.Append("<para>");
+                    // No change
+                    newValue.Append(ros);
+                    // Next time we find a line not surrounded by paras, we need to add the starting one first
+                    addStartParaNext = true;
                 }
-                newValue.Append(s);
-                if (moreThanOne && !s.EndsWith("</para>"))
+                else
                 {
-                    newValue.Append("</para>");
+                    if (addStartParaNext)
+                    {
+                        newValue.Append("<para>");
+                        addStartParaNext = false;
+                    }
+
+                    if (splitted[i].Equals("- or -"))
+                    {
+                        newValue.Append("-or-");
+                    }
+                    else
+                    {
+                        newValue.Append(ros);
+                    }
+                    if (!ros.EndsWith("</para>"))
+                    {
+                        if (ros[^1] is '.' or ':' || (i + 1) >= splitted.Length || splitted[i].Equals("-or-") || splitted[i].Equals("- or -"))
+                        {
+                            // We're done with this line
+                            newValue.Append("</para>");
+                            addStartParaNext = true;
+                        }
+                        else
+                        {
+                            // Space separator, the next line will get appended next
+                            newValue.Append(' ');
+                        }
+                    }
                 }
             }
 

src/PortToDocs/tests/PortToDocs.Strings.Tests.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Collections.Generic;
 using System.Text;
 using System.Xml.Linq;
@@ -2466,6 +2467,67 @@ I am paragraph number three.</summary>
             TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
         }
 
+        [Fact]
+        public void Para_EdgeCases()
+        {
+            // Convert triple slash new lines to para xml items. If there are paras too, keep them.
+
+            string originalIntellisense = @"<?xml version=""1.0""?>
+<doc>
+  <assembly>
+    <name>MyAssembly</name>
+  </assembly>
+  <members>
+    <member name=""T:MyNamespace.MyType"">
+      <summary><para>I am paragraph one with pre-existing paras.</para>
+I am paragraph number two but I am
+divided into two lines. I am paragraph three but I am in the same line, my spacing between lines should be ignored         
+               and the next newlines should be ignored.
+
+
+      <para>I am the fourth paragraph with pre-existing paras.</para>
+</summary>
+    </member>
+  </members>
+</doc>";
+
+            string originalDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
+  <TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
+  <AssemblyInfo>
+    <AssemblyName>MyAssembly</AssemblyName>
+  </AssemblyInfo>
+  <Docs>
+    <summary>To be added.</summary>
+    <remarks>To be added.</remarks>
+  </Docs>
+  <Members></Members>
+</Type>";
+
+            string expectedDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
+  <TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
+  <AssemblyInfo>
+    <AssemblyName>MyAssembly</AssemblyName>
+  </AssemblyInfo>
+  <Docs>
+    <summary>
+      <para>I am paragraph one with pre-existing paras.</para>
+      <para>I am paragraph number two but I am divided into two lines. I am paragraph three but I am in the same line, my spacing between lines should be ignored and the next newlines should be ignored.</para>
+      <para>I am the fourth paragraph with pre-existing paras.</para>
+    </summary>
+    <remarks>To be added.</remarks>
+  </Docs>
+  <Members></Members>
+</Type>";
+
+            Configuration configuration = new()
+            {
+                MarkdownRemarks = true
+            };
+            configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
+
+            TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
+        }
+
         [Fact]
         public void Convert_CodeDataDevCommentType_To_ExpectedElementNames()
         {
@@ -2619,6 +2681,4 @@ private static void TestWithStrings(List<string> intellisenseFiles, List<StringT
             }
         }
     }
-
-
 }