Replace "code data-dev-comment-type" and "xref data-throw-if-not-reso…

…lved" elements with the correct one (#171) * Replace code-data-dev-comment-type elements with the correct one. * Fix xref data-throw-if-not-resolved too * Better regex pattern * Even better regex
dotnet · Aug 6, 2024 · 1cc3a53 · 1cc3a53
1 parent a731e15
commit 1cc3a53
Show file tree

Hide file tree

Showing 2 changed files with 124 additions and 0 deletions.
diff --git a/src/PortToDocs/src/libraries/XmlHelper.cs b/src/PortToDocs/src/libraries/XmlHelper.cs
@@ -61,6 +61,8 @@ internal class XmlHelper
             { @"\<(see|seealso){1} cref\=""object""[ ]*\/\>",  "<see cref=\"T:System.Object\" />" },
             { @"\<(see|seealso){1} cref\=""dynamic""[ ]*\/\>", "<see langword=\"dynamic\" />" },
             { @"\<(see|seealso){1} cref\=""string""[ ]*\/\>",  "<see cref=\"T:System.String\" />" },
+            { @"<code data-dev-comment-type=""(?<elementName>[a-zA-Z0-9_]+)"">(?<elementValue>[a-zA-Z0-9_]+)</code>", "<see ${elementName}=\"${elementValue}\" />" },
+            { @"<xref data-throw-if-not-resolved=""[a-zA-Z0-9_]+"" uid=""(?<docId>[a-zA-Z0-9_,\<\>\.\@\#\$%^&`\(\)]+)""><\/xref>", "<see cref=\"T:${docId}\" />" },
         };
 
         private static readonly Dictionary<string, string> _replaceableMarkdownPatterns = new Dictionary<string, string> {
@@ -120,6 +122,8 @@ internal class XmlHelper
             // Params, typeparams, langwords
             { @"\<(typeparamref|paramref){1} name\=""(?'refNameContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>",  @"`${refNameContents}`" },
             { @"\<see langword\=""(?'seeLangwordContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>",  @"`${seeLangwordContents}`" },
+            { @"<code data-dev-comment-type=""[a-zA-Z0-9_]+"">(?<elementValue>[a-zA-Z0-9_]+)</code>", "`${elementValue}`" },
+            { @"<xref data-throw-if-not-resolved=""[a-zA-Z0-9_]+"" uid=""(?<docId>[a-zA-Z0-9_,\<\>\.]+)""><\/xref>", "<xref:${docId}>" },
         };
 
         private static readonly string[] _splittingSeparators = new string[] { "\r", "\n", "\r\n" };

diff --git a/src/PortToDocs/tests/PortToDocs.Strings.Tests.cs b/src/PortToDocs/tests/PortToDocs.Strings.Tests.cs
@@ -2466,6 +2466,126 @@ I am paragraph number three.</summary>
             TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
         }
 
+        [Fact]
+        public void Convert_CodeDataDevCommentType_To_ExpectedElementNames()
+        {
+            // The compiled xml files sometimes generate langwords, paramrefs and typeparamrefs with the format
+            // <code data-dev-comment-type="...">...</code>, so we need to convert them to the expected element type.
+
+            string originalIntellisense = @"<?xml version=""1.0""?>
+<doc>
+  <assembly>
+    <name>MyAssembly</name>
+  </assembly>
+  <members>
+    <member name=""T:MyNamespace.MyType"">
+      <summary>Langword <code data-dev-comment-type=""langword"">true</code>. Paramref <code data-dev-comment-type=""paramref"">myParam</code>. Typeparamref <code data-dev-comment-type=""typeparamref"">myTypeParam</code>.</summary>
+      <remarks>Langword <code data-dev-comment-type=""langword"">true</code>. Paramref <code data-dev-comment-type=""paramref"">myParam</code>. Typeparamref <code data-dev-comment-type=""typeparamref"">myTypeParam</code>.</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>Langword <see langword=""true"" />. Paramref <see paramref=""myParam"" />. Typeparamref <see typeparamref=""myTypeParam"" />.</summary>
+    <remarks>
+      <format type=""text/markdown""><![CDATA[
+
+## Remarks
+
+Langword `true`. Paramref `myParam`. Typeparamref `myTypeParam`.
+
+      ]]></format>
+    </remarks>
+  </Docs>
+  <Members></Members>
+</Type>";
+
+            Configuration configuration = new()
+            {
+                MarkdownRemarks = true
+            };
+            configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
+
+            TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
+        }
+
+        [Fact]
+        public void Convert_XrefDataThrowIfNotResolved_To_ExpectedElementNames()
+        {
+            // The compiled xml files sometimes generate type references with the format
+            // <xref data-throw-if-not-resolved="{bool}" uid="{DocId}"></xref>, so we need to convert them to the expected element type.
+
+            string originalIntellisense = @"<?xml version=""1.0""?>
+<doc>
+  <assembly>
+    <name>MyAssembly</name>
+  </assembly>
+  <members>
+    <member name=""T:MyNamespace.MyType"">
+      <summary>Type: <xref data-throw-if-not-resolved=""true"" uid=""MyNamespace.MyType""/>.</summary>
+      <remarks>Type: <xref data-throw-if-not-resolved=""true"" uid=""MyNamespace.MyType""></xref>.</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>Type: <see cref=""T:MyNamespace.MyType"" />.</summary>
+    <remarks>
+      <format type=""text/markdown""><![CDATA[
+
+## Remarks
+
+Type: <xref:MyNamespace.MyType>.
+
+      ]]></format>
+    </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);