8000 Replace "code data-dev-comment-type" and "xref data-throw-if-not-resolved" elements with the correct one by carlossanlop · Pull Request #171 · dotnet/api-docs-sync · GitHub
[go: up one dir, main page]
Skip to content

Replace "code data-dev-comment-type" and "xref data-throw-if-not-resolved" elements with the correct one #171

8000
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 4 commits into from
Aug 6, 2024
Merged

Replace "code data-dev-comment-type" and "xref data-throw-if-not-resolved" elements with the correct one #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1835795
Replace code-data-dev-comment-type elements with the correct one.
carlossanlop Aug 6, 2024
284ed7e
Fix xref data-throw-if-not-resolved too
carlossanlop Aug 6, 2024
81f2800
Better regex pattern
carlossanlop Aug 6, 2024
fee7440
Even better regex
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
4 changes: 4 additions & 0 deletions src/PortToDocs/src/libraries/XmlHelper.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> {
Expand Down Expand Up @@ -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" };
Expand Down
120 changes: 120 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 @@ -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);

Expand Down
Loading
0