Skip to content

Convert paragraphs divided by newlines into para items. #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 6, 2024
Merged

Convert paragraphs divided by newlines into para items. #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
278d07b
Convert paragraphs divided by newlines into para items.
carlossanlop Aug 6, 2024
b856dbe
Merge remote-tracking branch 'dotnet/main' into ParaItems
carlossanlop Aug 6, 2024
5b7e75f
Update the filesystem tests
carlossanlop Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/PortToDocs/src/app/PortToDocs.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<Nullable>enable</Nullable>
<IsPackable>true</IsPackable>
<PackAsTool>true</PackAsTool>
<Version>1.2</Version>
<Version>1.3</Version>
</PropertyGroup>

<ItemGroup>
Expand Down
30 changes: 29 additions & 1 deletion src/PortToDocs/src/libraries/XmlHelper.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using System.Xml;
using System.Xml.Linq;
Expand Down Expand Up @@ -120,6 +122,9 @@ internal class XmlHelper
{ @"\<see langword\=""(?'seeLangwordContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>", @"`${seeLangwordContents}`" },
};

private static readonly string[] _splittingSeparators = new string[] { "\r", "\n", "\r\n" };
private static readonly StringSplitOptions _splittingStringSplitOptions = StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries;

public static string GetAttributeValue(XElement parent, string name)
{
if (parent == null)
Expand Down Expand Up @@ -182,12 +187,35 @@ public static string GetNodesInPlainText(XElement element)

public static string GetFormattedAsXml(string value, bool removeUndesiredEndlines)
{
string updatedValue = removeUndesiredEndlines ? RemoveUndesiredEndlines(value) : value;
string updatedValue = ReplaceEndLinesWithParas(value);
updatedValue = removeUndesiredEndlines ? RemoveUndesiredEndlines(updatedValue) : updatedValue;
updatedValue = ReplaceNormalElementPatterns(updatedValue);
updatedValue = SubstituteRegexPatterns(updatedValue, _replaceableNormalElementRegexPatterns);
return updatedValue;
}

private static string ReplaceEndLinesWithParas(string updatedValue)
{
string[] splitted = updatedValue.Split(_splittingSeparators, _splittingStringSplitOptions);
bool moreThanOne = splitted.Count() > 1;

StringBuilder newValue = new();
foreach (string s in splitted)
{
if (moreThanOne && !s.StartsWith("<para>"))
{
newValue.Append("<para>");
}
newValue.Append(s);
if (moreThanOne && !s.EndsWith("</para>"))
{
newValue.Append("</para>");
}
}

return newValue.ToString();
}

public static string GetFormattedAsMarkdown(string value, bool isMember)
{
XElement xeFormat = new XElement("format");
Expand Down
111 changes: 111 additions & 0 deletions src/PortToDocs/tests/PortToDocs.Strings.Tests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2355,6 +2355,117 @@ public void Preserve_Para()
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
}

[Fact]
public void Convert_NewLines_To_Para()
{
// Convert triple slash new lines to para xml items.

string originalIntellisense = @"<?xml version=""1.0""?>
<doc>
<assembly>
<name>MyAssembly</name>
</assembly>
<members>
<member name=""T:MyNamespace.MyType"">
<summary>I am paragraph one.
I am paragraph number two.</summary>
<remarks>I have no newlines.</remarks>
</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.</para>
<para>I am paragraph number two.</para>
</summary>
<remarks>I have no newlines.</remarks>
</Docs>
<Members></Members>
</Type>";

Configuration configuration = new()
{
MarkdownRemarks = false
};
configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);

TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
}

[Fact]
public void Convert_NewLines_To_Para_Preserve_Existing_Para()
{
// 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.</para>
I am paragraph number two.
I am paragraph number three.</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.</para>
<para>I am paragraph number two.</para>
<para>I am paragraph number three.</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);
}

private static void TestWithStrings(string intellisenseFile, string originalDocsFile, string expectedDocsFile, Configuration configuration) =>
TestWithStrings(intellisenseFile, new List<StringTestData>() { new StringTestData(originalDocsFile, expectedDocsFile) }, configuration);

Expand Down
12 changes: 6 additions & 6 deletions src/PortToDocs/tests/TestData/Exception_ExistingCref/xml_expected/MyAssembly/MyType.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="MyType" FullName="MyNamespace.MyType">
<Type Name="MyType" FullName="MyNamespace.MyType">
<TypeSignature Language="DocId" Value="T:MyNamespace.MyType" />
<AssemblyInfo>
<AssemblyName>MyAssembly</AssemblyName>
Expand Down Expand Up @@ -32,11 +32,11 @@
<exception cref="T:System.EightyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8.</exception>
<exception cref="T:System.SeventyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6 Word7.</exception>
<exception cref="T:System.SixtyPercentCollisionException">Word1 Word2 Word3 Word4 Word5 Word6.</exception>
<exception cref="T:System.FiftyPercentCollisionException">Word1 Word2 Word3 Word4 Word5.

-or-

Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8 Word9 Word10.</exception>
<exception cref="T:System.FiftyPercentCollisionException">
<para>Word1 Word2 Word3 Word4 Word5.</para>
<para>-or-</para>
<para>Word1 Word2 Word3 Word4 Word5 Word6 Word7 Word8 Word9 Word10.</para>
</exception>
</Docs>
</Member>
</Members>
Expand Down
24 changes: 10 additions & 14 deletions src/PortToDocs/tests/TestData/Exceptions/xml_expected/MyAssembly/MyType.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<Type Name="MyType" FullName="MyNamespace.MyType">
<Type Name="MyType" FullName="MyNamespace.MyType">
<TypeSignature Language="DocId" Value="T:MyNamespace.MyType" />
<AssemblyInfo>
<AssemblyName>MyAssembly</AssemblyName>
Expand Down Expand Up @@ -29,19 +29,15 @@
<summary>This is the method summary.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">This is the original text of ArgumentNullException thrown for MyMethod.</exception>
<exception cref="T:System.IndexOutOfRangeException">This is the original text of IndexOutOfRangeException thrown for MyMethod.

-or-

A proper alternative.

-or-

An improper alternative.

-or-

A somewhat proper alternative.</exception>
<exception cref="T:System.IndexOutOfRangeException">
<para>This is the original text of IndexOutOfRangeException thrown for MyMethod.</para>
<para>-or-</para>
<para>A proper alternative.</para>
<para>-or-</para>
<para>An improper alternative.</para>
<para>-or-</para>
<para>A somewhat proper alternative.</para>
</exception>
</Docs>
</Member>
</Members>
Expand Down
Loading