8000 Replace "code data-dev-comment-type" and "xref data-throw-if-not-reso… · dotnet/api-docs-sync@1cc3a53 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1cc3a53

Browse files
carlossanlopcarlossanlop
authored
Replace "code data-dev-comment-type" and "xref data-throw-if-not-resolved" 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
1 parent a731e15 commit 1cc3a53

File tree

2 files changed

+124
-0
lines changed

2 files changed

+124
-0
lines changed

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ internal class XmlHelper
6161
{ @"\<(see|seealso){1} cref\=""object""[ ]*\/\>", "<see cref=\"T:System.Object\" />" },
6262
{ @"\<(see|seealso){1} cref\=""dynamic""[ ]*\/\>", "<see langword=\"dynamic\" />" },
6363
{ @"\<(see|seealso){1} cref\=""string""[ ]*\/\>", "<see cref=\"T:System.String\" />" },
64+
{ @"<code data-dev-comment-type=""(?<elementName>[a-zA-Z0-9_]+)"">(?<elementValue>[a-zA-Z0-9_]+)</code>", "<see ${elementName}=\"${elementValue}\" />" },
65+
{ @"<xref data-throw-if-not-resolved=""[a-zA-Z0-9_]+"" uid=""(?<docId>[a-zA-Z0-9_,\<\>\.\@\#\$%^&`\(\)]+)""><\/xref>", "<see cref=\"T:${docId}\" />" },
6466
};
6567

6668
private static readonly Dictionary<string, string> _replaceableMarkdownPatterns = new Dictionary<string, string> {
@@ -120,6 +122,8 @@ internal class XmlHelper
120122
// Params, typeparams, langwords
121123
{ @"\<(typeparamref|paramref){1} name\=""(?'refNameContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>", @"`${refNameContents}`" },
122124
{ @"\<see langword\=""(?'seeLangwordContents'[a-zA-Z0-9_\-]+)""[ ]*\/\>", @"`${seeLangwordContents}`" },
125+
{ @"<code data-dev-comment-type=""[a-zA-Z0-9_]+"">(?<elementValue>[a-zA-Z0-9_]+)</code>", "`${elementValue}`" },
126+
{ @"<xref data-throw-if-not-resolved=""[a-zA-Z0-9_]+"" uid=""(?<docId>[a-zA-Z0-9_,\<\>\.]+)""><\/xref>", "<xref:${docId}>" },
123127
};
124128

125129
private static readonly string[] _splittingSeparators = new string[] { "\r", "\n", "\r\n" };

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2466,6 +2466,126 @@ I am paragraph number three.</summary>
24662466
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
24672467
}
24682468

2469+
[Fact]
2470+
public void Convert_CodeDataDevCommentType_To_ExpectedElementNames()
2471+
{
2472+
// The compiled xml files sometimes generate langwords, paramrefs and typeparamrefs with the format
2473+
// <code data-dev-comment-type="...">...</code>, so we need to convert them to the expected element type.
2474+
2475+
string originalIntellisense = @"<?xml version=""1.0""?>
2476+
<doc>
2477+
<assembly>
2478+
<name>MyAssembly</name>
2479+
</assembly>
2480+
<members>
2481+
<member name=""T:MyNamespace.MyType"">
2482+
<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>
2483+
<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>
2484+
</member>
2485+
</members>
2486+
</doc>";
2487+
2488+
string originalDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2489+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2490+
<AssemblyInfo>
2491+
<AssemblyName>MyAssembly</AssemblyName>
2492+
</AssemblyInfo>
2493+
<Docs>
2494+
<summary>To be added.</summary>
2495+
<remarks>To be added.</remarks>
2496+
</Docs>
2497+
<Members></Members>
2498+
</Type>";
2499+
2500+
string expectedDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2501+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2502+
<AssemblyInfo>
2503+
<AssemblyName>MyAssembly</AssemblyName>
2504+
</AssemblyInfo>
2505+
<Docs>
2506+
<summary>Langword <see langword=""true"" />. Paramref <see paramref=""myParam"" />. Typeparamref <see typeparamref=""myTypeParam"" />.</summary>
2507+
<remarks>
2508+
<format type=""text/markdown""><![CDATA[
2509+
2510+
## Remarks
2511+
2512+
Langword `true`. Paramref `myParam`. Typeparamref `myTypeParam`.
2513+
2514+
]]></format>
2515+
</remarks>
2516+
</Docs>
2517+
<Members></Members>
2518+
</Type>";
2519+
2520+
Configuration configuration = new()
2521+
{
2522+
MarkdownRemarks = true
2523+
};
2524+
configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
2525+
2526+
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
2527+
}
2528+
2529+
[Fact]
2530+
public void Convert_XrefDataThrowIfNotResolved_To_ExpectedElementNames()
2531+
{
2532+
// The compiled xml files sometimes generate type references with the format
2533+
// <xref data-throw-if-not-resolved="{bool}" uid="{DocId}"></xref>, so we need to convert them to the expected element type.
2534+
2535+
string originalIntellisense = @"<?xml version=""1.0""?>
2536+
<doc>
2537+
<assembly>
2538+
<name>MyAssembly</name>
2539+
</assembly>
2540+
<members>
2541+
<member name=""T:MyNamespace.MyType"">
2542+
<summary>Type: <xref data-throw-if-not-resolved=""true"" uid=""MyNamespace.MyType""/>.</summary>
2543+
<remarks>Type: <xref data-throw-if-not-resolved=""true"" uid=""MyNamespace.MyType""></xref>.</remarks>
2544+
</member>
2545+
</members>
2546+
</doc>";
2547+
2548+
string originalDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2549+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2550+
<AssemblyInfo>
2551+
<AssemblyName>MyAssembly</AssemblyName>
2552+
</AssemblyInfo>
2553+
<Docs>
2554+
<summary>To be added.</summar A3E2 y>
2555+
<remarks>To be added.</remarks>
2556+
</Docs>
2557+
<Members></Members>
2558+
</Type>";
2559+
2560+
string expectedDocs = @"<Type Name=""MyType"" FullName=""MyNamespace.MyType"">
2561+
<TypeSignature Language=""DocId"" Value=""T:MyNamespace.MyType"" />
2562+
<AssemblyInfo>
2563+
<AssemblyName>MyAssembly</AssemblyName>
2564+
</AssemblyInfo>
2565+
<Docs>
2566+
<summary>Type: <see cref=""T:MyNamespace.MyType"" />.</summary>
2567+
<remarks>
2568+
<format type=""text/markdown""><![CDATA[
2569+
2570+
## Remarks
2571+
2572+
Type: <xref:MyNamespace.MyType>.
2573+
2574+
]]></format>
2575+
</remarks>
2576+
</Docs>
2577+
<Members></Members>
2578+
</Type>";
2579+
2580+
Configuration configuration = new()
2581+
{
2582+
MarkdownRemarks = true
2583+
};
2584+
configuration.IncludedAssemblies.Add(FileTestData.TestAssembly);
2585+
2586+
TestWithStrings(originalIntellisense, originalDocs, expectedDocs, configuration);
2587+
}
2588+
24692589
private static void TestWithStrings(string intellisenseFile, string originalDocsFile, string expectedDocsFile, Configuration configuration) =>
24702590
TestWithStrings(intellisenseFile, new List<StringTestData>() { new StringTestData(originalDocsFile, expectedDocsFile) }, configuration);
24712591

0 commit comments

Comments
 (0)
0