8000 Convert paragraphs divided by newlines into para items. (#170) · dotnet/api-docs-sync@a731e15 · GitHub
[go: up one dir, main page]
Skip to content

Commit a731e15

Browse files
carlossanlopcarlossanlop
authored
Convert paragraphs divided by newlines into para items. (#170)
* Convert paragraphs divided by newlines into para items. * Update the filesystem tests
1 parent e92572b commit a731e15

File tree

5 files changed

+157
-22
lines changed

5 files changed

+157
-22
lines changed

‎src/PortToDocs/src/app/PortToDocs.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<Nullable>enable</Nullable>
88
<IsPackable>true</IsPackable>
99
<PackAsTool>true</PackAsTool>
10-
<Version>1.2</Version>
10+
<Version>1.3</Version>
1111
</PropertyGroup>
1212

1313
<ItemGroup>

‎src/PortToDocs/src/libraries/XmlHelper.cs

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
44
using System;
55
using System.Collections.Generic;
6+
using System.Linq;
7+
using System.Text;
68
using System.Text.RegularExpressions;
79
using System.Xml;
810
using System.Xml.Linq;
@@ -120,6 +122,9 @@ internal class XmlHelper
120122
{ @"\<see langword\=""(?'seeLangwordContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>", @"`${seeLangwordContents}`" },
121123
};
122124

125+
private static readonly string[] _splittingSeparators = new string[] { "\r", "\n", "\r\n" };
126+
private static readonly StringSplitOptions _splittingStringSplitOptions = StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries;
127+
123128
public static string GetAttributeValue(XElement parent, string name)
124129
{
125130
if (parent == null)
@@ -182,12 +187,35 @@ public static string GetNodesInPlainText(XElement element)
182187

183188
public static string GetFormattedAsXml(string value, bool removeUndesiredEndlines)
184189
{
185-
string updatedValue = removeUndesiredEndlines ? RemoveUndesiredEndlines(value) : value;
190+
string updatedValue = ReplaceEndLinesWithParas(value);
191+
updatedValue = removeUndesiredEndlines ? RemoveUndesiredEndlines(updatedValue) : updatedValue;
186192
updatedValue = ReplaceNormalElementPatterns(updatedValue);
187193
updatedValue = SubstituteRegexPatterns(updatedValue, _replaceableNormalElementRegexPatterns);
188194
return updatedValue;
189195
}
190196

197+
private static string ReplaceEndLinesWithParas(string updatedValue)
198+
{
199+
string[] splitted = updatedValue.Split(_splittingSeparators, _splittingStringSplitOptions);
200+
bool moreThanOne = splitted.Count() > 1;
201+
202+
StringBuilder newValue = new();
203+
foreach (string s in splitted)
204+
{
205+
if (moreThanOne && !s.StartsWith("<para>"))
206+
{
207+
newValue.Append("<para>");
208+
}
209+
newValue.Append(s);
210+
if (moreThanOne && !s.EndsWith("</para>"))
211+
{
212+
newValue.Append("</para>");
213+
}
214+
}
215+
216+
return newValue.ToString();
217+
}
218+
191219
public static string GetFormattedAsMarkdown(string value, bool isMember)
192220
{
193221
XElement xeFormat = new XElement("format");

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2355,6 +2355,117 @@ public void Preserve_Para()
23552355
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
23562356
}
23572357

2358+
[Fact]
2359+
public void Convert_NewLines_To_Para()
2360+
{
2361+
// Convert triple slash new lines to para xml items.
2362+
2363+
string originalIntellisense = @"<?xml version=""1.0""?>
2364+
<doc>
2365+
<assembly>
2366+
<name>MyAssembly</name>
2367+
</assembly>
2368+
<members>
2369+
<member name=""T:MyNamespace.MyType"">
2370+
<summary>I am paragraph one.
2371+
I am paragraph number two.</summary>
2372+
<remarks>I have no newlines.</remarks>
2373+
</member>
2374+
</members>
2375+
</doc>";
2376+
2377+
string originalDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2378+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2379+
<AssemblyInfo>
2380+
<AssemblyName>MyAssembly</AssemblyName>
2381+
</AssemblyInfo>
2382+
<Docs>
2383+
<summary>To be added.</summary>
2384+
<remarks>To be added.</remarks>
2385+
</Docs>
2386+
<Members></Members>
2387+
</Type>";
2388+
2389+
string expectedDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2390+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2391+
<AssemblyInfo>
2392+
<AssemblyName>MyAssembly</AssemblyName>
2393+
</AssemblyInfo>
2394+
<Docs>
2395+
<summary>
2396+
<para>I am paragraph one.</para>
2397+
<para>I am paragraph number two.</para>
2398+
</summary>
2399+
<remarks>I have no newlines.</remarks>
2400+
</Docs>
2401+
<Members></Members>
2402+
</Type>";
2403+
2404+
Configuration configuration = new()
2405+
{
2406+
MarkdownRemarks = false
2407+
};
2408+
configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
2409+
2410+
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
2411+
}
2412+
2413+
[Fact]
2414+
public void Convert_NewLines_To_Para_Preserve_Existing_Para()
2415+
{
2416+
// Convert triple slash new lines to para xml items. If there are paras too, keep them.
2417+
2418+
string originalIntellisense = @"<?xml version=""1.0""?>
2419+
<doc>
2420+
<assembly>
2421+
<name>MyAssembly</name>
2422+
</assembly>
2423+
<members>
2424+
<member name=""T:MyNamespace.MyType"">
10000 2425+
<summary><para>I am paragraph one.</para>
2426+
I am paragraph number two.
2427+
I am paragraph number three.</summary>
2428+
</member>
2429+
</members>
2430+
</doc>";
2431+
2432+
string originalDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2433+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2434+
<AssemblyInfo>
2435+
<AssemblyName>MyAssembly</AssemblyName>
2436+
</AssemblyInfo>
2437+
<Docs>
2438+
<summary>To be added.</summary>
2439+
<remarks>To be added.</remarks>
2440+
</Docs>
2441+
<Members></Members>
2442+
</Type>";
2443+
2444+
string expectedDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2445+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2446+
<AssemblyInfo>
2447+
<AssemblyName>MyAssembly</AssemblyName>
2448+
</AssemblyInfo>
2449+
<Docs>
2450+
<summary>
2451+
<para>I am paragraph one.</para>
2452+
<para>I am paragraph number two.</para>
2453+
<para>I am paragraph number three.</para>
2454+
</summary>
2455+
<remarks>To be added.</remarks>
2456+
</Docs>
2457+
<Members></Members>
2458+
</Type>";
2459+
2460+
Configuration configuration = new()
2461+
{
2462+
MarkdownRemarks = true
2463+
};
2464+
configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
2465+
2466+
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
2467+
}
2468+
23582469
private static void TestWithStrings(string intellisenseFile, string originalDocsFile, string expectedDocsFile, Configuration configuration) =>
23592470
TestWithStrings(intellisenseFile, new List<StringTestData>() { new StringTestData(originalDocsFile, expectedDocsFile) }, configuration);
23602471

‎src/PortToDocs/tests/TestData/Exception_ExistingCref/xml_expected/MyAssembly/MyType.xml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<Type Name="MyType" FullName="MyNamespace.MyType">
1+
<Type Name="MyType" FullName="MyNamespace.MyType">
22
<TypeSignature Language="DocId" Value="T:MyNamespace.MyType" />
33
<AssemblyInfo>
44
<AssemblyName>MyAssembly</AssemblyName>
@@ -32,11 +32,11 @@
3232
<exception cref="T:System.EightyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8.</exception>
3333
<exception cref="T:System.SeventyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6 Word7.</exception>
3434
<exception cref="T:System.SixtyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6.</exception>
35-
<exception cref="T:System.FiftyPercentCollisionException">Word1 Word2 Word3 Word4 Word5.
36-
37-
-or-
38-
39-
Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8 Word9 Word10.</exception>
35+
<exception cref="T:System.FiftyPercentCollisionException">
36+
<para>Word1 Word2 Word3 Word4 Word5.</para>
37+
<para>-or-</para>
38+
<para>Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8 Word9 Word10.</para>
39+
</exception>
4040
</Docs>
4141
</Member>
4242
</Members>

‎src/PortToDocs/tests/TestData/Exceptions/xml_expected/MyAssembly/MyType.xml

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<Type Name="MyType" FullName="MyNamespace.MyType">
1+
<Type Name="MyType" FullName="MyNamespace.MyType">
22
<TypeSignature Language="DocId" Value="T:MyNamespace.MyType" />
33
1CF5 <AssemblyInfo>
44
<AssemblyName>MyAssembly</AssemblyName>
@@ -29,19 +29,15 @@
2929
<summary>This is the method summary.</summary>
3030
<remarks>To be added.</remarks>
3131
<exception cref="T:System.ArgumentNullException">This is the original text of ArgumentNullException thrown for MyMethod.</exception>
32-
<exception cref="T:System.IndexOutOfRangeException">This is the original text of IndexOutOfRangeException thrown for MyMethod.
33-
34-
-or-
35-
36-
A proper alternative.
37-
38-
-or-
39-
40-
An improper alternative.
41-
42-
-or-
43-
44-
A somewhat proper alternative.</exception>
32+
<exception cref="T:System.IndexOutOfRangeException">
33+
<para>This is the original text of IndexOutOfRangeException thrown for MyMethod.</para>
34+
<para>-or-</para>
35+
<para>A proper alternative.</para>
36+
<para>-or-</para>
37+
<para>An improper alternative.</para>
38+
<para>-or-</para>
39+
<para>A somewhat proper alternative.</para>
40+
</exception>
4541
</Docs>
4642
</Member>
4743
</Members>

0 commit comments

Comments
 (0)
0