|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
using Microsoft.CodeAnalysis.Shared.Utilities;
using Roslyn.Test.Utilities;
using Xunit;
namespace Microsoft.CodeAnalysis.UnitTests;
public sealed class DocumentationCommentTests
{
[Fact]
public void ParseEmptyXmlFragment()
{
var document = DocumentationComment.FromXmlFragment("");
Assert.Null(document.ExampleText);
Assert.Null(document.ReturnsText);
Assert.Null(document.ValueText);
Assert.Null(document.SummaryText);
}
[Fact]
public void ParseFullTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>Hello, world!</summary>
<returns>42.</returns>
<value>43.</value>
<example>goo.Bar();</example>
<param name=""goo"">A goo.</param>
<typeparam name=""T"">A type.</typeparam>
<exception cref=""System.Exception"">An exception</exception>
<remarks>A remark</remarks>");
Assert.Equal("Hello, world!", comment.SummaryText);
Assert.Equal("42.", comment.ReturnsText);
Assert.Equal("43.", comment.ValueText);
Assert.Equal("goo.Bar();", comment.ExampleText);
Assert.Equal("goo", comment.ParameterNames[0]);
Assert.Equal("A goo.", comment.GetParameterText("goo"));
Assert.Equal("T", comment.TypeParameterNames[0]);
Assert.Equal("A type.", comment.GetTypeParameterText("T"));
Assert.Equal("System.Exception", comment.ExceptionTypes[0]);
Assert.Equal("An exception", comment.GetExceptionTexts("System.Exception")[0]);
Assert.Equal("A remark", comment.RemarksText);
}
[Fact]
public void ParseFullTagEmptyValues()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary></summary>
<returns></returns>
<value></value>
<example></example>
<param name=""goo""></param>
<typeparam name=""T""></typeparam>
<exception cref=""System.Exception""></exception>
<remarks></remarks>");
Assert.Equal(string.Empty, comment.SummaryText);
Assert.Equal(string.Empty, comment.ReturnsText);
Assert.Equal(string.Empty, comment.ValueText);
Assert.Equal(string.Empty, comment.ExampleText);
Assert.Equal("goo", comment.ParameterNames[0]);
Assert.Equal(string.Empty, comment.GetParameterText("goo"));
Assert.Equal("T", comment.TypeParameterNames[0]);
Assert.Equal(string.Empty, comment.GetTypeParameterText("T"));
Assert.Equal("System.Exception", comment.ExceptionTypes[0]);
Assert.Equal(string.Empty, comment.GetExceptionTexts("System.Exception")[0]);
Assert.Equal(string.Empty, comment.RemarksText);
}
[Fact]
public void ParseTagWithMultipleSummaries()
{
var comment = DocumentationComment.FromXmlFragment("<summary>Summary 1</summary><summary>Summary 2</summary>");
Assert.Equal("Summary 1", comment.SummaryText);
}
[Fact(Skip = "Bug 522741")]
[WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/522741")]
public void ParseTagWithMultiLineComments()
{
var comment = DocumentationComment.FromXmlFragment(@"<summary>
Summary 1
Summary 2
</summary>");
Assert.Equal("Summary 1 Summary 2", comment.SummaryText);
}
[Fact]
public void ParseInvalidXML()
{
var comment = DocumentationComment.FromXmlFragment("<summary>goo");
Assert.True(comment.HadXmlParseError);
Assert.Null(comment.SummaryText);
}
[Fact]
public void PreserveParameterNameOrdering()
{
var comment = DocumentationComment.FromXmlFragment(
@"<param name=""z"">Z</param>
<param name=""a"">A</param>
<param name=""b"">B</param>");
Assert.Equal("z", comment.ParameterNames[0]);
Assert.Equal("a", comment.ParameterNames[1]);
Assert.Equal("b", comment.ParameterNames[2]);
}
[Fact]
public void PreserveTypeParameterNameOrdering()
{
var comment = DocumentationComment.FromXmlFragment(
@"<typeparam name=""z"">Z</typeparam>
<typeparam name=""a"">A</typeparam>
<typeparam name=""b"">B</typeparam>");
Assert.Equal("z", comment.TypeParameterNames[0]);
Assert.Equal("a", comment.TypeParameterNames[1]);
Assert.Equal("b", comment.TypeParameterNames[2]);
}
[Fact]
public void PreserveExceptionTypeOrdering()
{
var comment = DocumentationComment.FromXmlFragment(
@"<exception cref=""z"">Z</exception>
<exception cref=""a"">A</exception>
<exception cref=""b"">B</exception>");
Assert.Equal("z", comment.ExceptionTypes[0]);
Assert.Equal("a", comment.ExceptionTypes[1]);
Assert.Equal("b", comment.ExceptionTypes[2]);
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/546732")]
public void UnknownTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>This is a summary.</summary>
<RandomTag>This is another summary.</RandomTag>
<param name=""a"">The param named 'a'</param>");
Assert.Equal("This is a summary.", comment.SummaryText);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("The param named 'a'", comment.GetParameterText("a"));
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/546732")]
public void TextOutsideTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<summary>This is a summary.</summary>
This is random top-level text.
<param name=""a"">The param named 'a'</param>");
Assert.Equal("This is a summary.", comment.SummaryText);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("The param named 'a'", comment.GetParameterText("a"));
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/546732")]
public void SingleTopLevelTag()
{
var comment = DocumentationComment.FromXmlFragment(
@"<member>
<summary>This is a summary.</summary>
This is random top-level text.
<param name=""a"">The param named 'a'</param>
</member>");
Assert.Equal("This is a summary.", comment.SummaryText);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("The param named 'a'", comment.GetParameterText("a"));
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/530760")]
public void MultipleParamsWithSameName()
{
var comment = DocumentationComment.FromXmlFragment(
@"<param name=""a"">This comment should be retained.</param>
<param name=""a"">This comment should not be retained.</param>");
Assert.Equal(1, comment.ParameterNames.Length);
Assert.Equal("a", comment.ParameterNames[0]);
Assert.Equal("This comment should be retained.", comment.GetParameterText("a"));
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/530760")]
public void MultipleTypeParamsWithSameName()
{
var comment = DocumentationComment.FromXmlFragment(
@"<typeparam name=""a"">This comment should be retained.</typeparam>
<typeparam name=""a"">This comment should not be retained.</typeparam>");
Assert.Equal(1, comment.TypeParameterNames.Length);
Assert.Equal("a", comment.TypeParameterNames[0]);
Assert.Equal("This comment should be retained.", comment.GetTypeParameterText("a"));
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/530760")]
public void MultipleExceptionsWithSameName()
{
var comment = DocumentationComment.FromXmlFragment(
@"<exception cref=""A"">First A description</exception>
<exception cref=""B"">First B description</exception>
<exception cref=""A"">Second A description</exception>
<exception cref=""B"">Second B description</exception>");
Assert.Equal(2, comment.ExceptionTypes.Length);
Assert.Equal("A", comment.ExceptionTypes[0]);
Assert.Equal("B", comment.ExceptionTypes[1]);
Assert.Equal(2, comment.GetExceptionTexts("A").Length);
Assert.Equal("First A description", comment.GetExceptionTexts("A")[0]);
Assert.Equal("Second A description", comment.GetExceptionTexts("A")[1]);
Assert.Equal(2, comment.GetExceptionTexts("B").Length);
Assert.Equal("First B description", comment.GetExceptionTexts("B")[0]);
Assert.Equal("Second B description", comment.GetExceptionTexts("B")[1]);
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/530760")]
public void NoExceptionWithGivenName()
{
var comment = DocumentationComment.FromXmlFragment(@"<summary>This is a summary</summary>");
Assert.Equal(0, comment.GetExceptionTexts("A").Length);
}
[Fact, WorkItem("http://vstfdevdiv:8080/DevDiv2/DevDiv/_workitems/edit/531189")]
public void NoNameAttribute()
{
var comment = DocumentationComment.FromXmlFragment(@"<param/><typeparam/><exception/>");
Assert.Equal(0, comment.ParameterNames.Length);
Assert.Equal(0, comment.TypeParameterNames.Length);
Assert.Equal(0, comment.ExceptionTypes.Length);
}
[Fact, WorkItem(612456, "DevDiv2/DevDiv")]
public void ReservedXmlNamespaceInName()
{
var fragment = @"<summary><xmlns:boo /></summary>";
var comments = DocumentationComment.FromXmlFragment(fragment);
Assert.Equal(fragment, comments.FullXmlFragment);
Assert.True(comments.HadXmlParseError);
}
[Fact, WorkItem("https://github.com/dotnet/roslyn/pull/18901")]
public void TrimEachLine()
{
var multiLineText = @"
Hello
World .
+
.......
123
1";
var fullXml = $@"<summary>{multiLineText}</summary>
<returns>{multiLineText}</returns>
<value>{multiLineText}</value>
<example>{multiLineText}</example>
<param name=""goo"">{multiLineText}</param>
<typeparam name=""T"">{multiLineText}</typeparam>
<remarks>{multiLineText}</remarks>";
var expected = @"Hello
World .
+
.......
123
1";
var comment = DocumentationComment.FromXmlFragment(fullXml);
Assert.Equal(expected, comment.SummaryText);
Assert.Equal(expected, comment.ReturnsText);
Assert.Equal(expected, comment.ValueText);
Assert.Equal(expected, comment.ExampleText);
Assert.Equal(expected, comment.GetParameterText("goo"));
Assert.Equal(expected, comment.GetTypeParameterText("T"));
Assert.Equal(expected, comment.RemarksText);
}
[Fact, WorkItem("https://github.com/dotnet/roslyn/pull/18901")]
public void TrimEachLineCommonOffset()
{
var multiLineText = @"
Hello
World .
+
.......
123
1";
var fullXml = $@"<summary>{multiLineText}</summary>
<returns>{multiLineText}</returns>
<value>{multiLineText}</value>
<example>{multiLineText}</example>
<param name=""goo"">{multiLineText}</param>
<typeparam name=""T"">{multiLineText}</typeparam>
<remarks>{multiLineText}</remarks>";
var expected = @"Hello
World .
+
.......
123
1";
var comment = DocumentationComment.FromXmlFragment(fullXml);
Assert.Equal(expected, comment.SummaryText);
Assert.Equal(expected, comment.ReturnsText);
Assert.Equal(expected, comment.ValueText);
Assert.Equal(expected, comment.ExampleText);
Assert.Equal(expected, comment.GetParameterText("goo"));
Assert.Equal(expected, comment.GetTypeParameterText("T"));
Assert.Equal(expected, comment.RemarksText);
}
}
|