From 4c19f1b28df66eaf3035105ec5b8bb35bfeb6869 Mon Sep 17 00:00:00 2001 From: robinsedlaczek Date: Tue, 3 Nov 2015 19:32:48 +0100 Subject: [PATCH 01/13] Improve SyntaxFactory for documentation comments and add one first test. --- .../CSharp/Portable/PublicAPI.Unshipped.txt | 45 ++- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 279 ++++++++++++++++++ .../Test/Syntax/Syntax/SyntaxFactoryTests.cs | 27 ++ 3 files changed, 350 insertions(+), 1 deletion(-) diff --git a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt index 437c4beb5a296..c9c6f60fb3f55 100644 --- a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt @@ -50,11 +50,54 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this M static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this Microsoft.CodeAnalysis.SyntaxToken token, string indentation, bool elasticTrivia) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this Microsoft.CodeAnalysis.SyntaxTriviaList list, string indentation = " ", string eol = "\r\n", bool elasticTrivia = false) -> Microsoft.CodeAnalysis.SyntaxTriviaList static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this Microsoft.CodeAnalysis.SyntaxTriviaList list, string indentation, bool elasticTrivia) -> Microsoft.CodeAnalysis.SyntaxTriviaList +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.DocumentationComment(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.DocumentationCommentTriviaSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ExceptionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.LoadDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken file, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.LoadDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken hashToken, Microsoft.CodeAnalysis.SyntaxToken loadKeyword, Microsoft.CodeAnalysis.SyntaxToken file, Microsoft.CodeAnalysis.SyntaxToken endOfDirectiveToken, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.PreliminaryElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ShebangDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken hashToken, Microsoft.CodeAnalysis.SyntaxToken exclamationToken, Microsoft.CodeAnalysis.SyntaxToken endOfDirectiveToken, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ShebangDirectiveTrivia(bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlCrefAttribute(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlCrefAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlCrefAttribute(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, Microsoft.CodeAnalysis.CSharp.SyntaxKind quoteKind) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlCrefAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlElement(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlElement(string localName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlEmptyElement(string localName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExceptionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(string localName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNameAttribute(string parameterName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNewLine() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNullKeywordElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParaElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParaElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamElement(string parameterName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamElement(string parameterName, params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamRefElement(string parameterName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPlaceholderElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPlaceholderElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlRemarksElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlRemarksElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlReturnsElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlReturnsElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlSeeAlsoElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlSeeAlsoElement(System.Uri linkAddress, Microsoft.CodeAnalysis.SyntaxList linkText) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlSeeElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlSummaryElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlSummaryElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlText(params Microsoft.CodeAnalysis.SyntaxToken[] textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlText(string value) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.CSharp.SyntaxKind quoteKind, Microsoft.CodeAnalysis.SyntaxTokenList textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, Microsoft.CodeAnalysis.CSharp.SyntaxKind quoteKind, Microsoft.CodeAnalysis.SyntaxTokenList textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, params Microsoft.CodeAnalysis.SyntaxToken[] textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, string value) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string value) -> Microsoft.CodeAnalysis.SyntaxToken +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(bool continueXmlDocumentationComment) -> Microsoft.CodeAnalysis.SyntaxToken +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement(bool static, bool instance) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlValueElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlValueElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitLoadDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax node) -> void virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitShebangDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax node) -> void virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitLoadDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax node) -> TResult -virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitShebangDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax node) -> TResult +virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitShebangDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax node) -> TResult \ No newline at end of file diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index c4b7163fc3266..bd8c483eadccd 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -9,6 +9,7 @@ using Microsoft.CodeAnalysis.CSharp.Syntax; using Microsoft.CodeAnalysis.Text; using InternalSyntax = Microsoft.CodeAnalysis.CSharp.Syntax.InternalSyntax; +using System.Xml.Linq; namespace Microsoft.CodeAnalysis.CSharp { @@ -663,6 +664,284 @@ public static SyntaxToken XmlEntity(SyntaxTriviaList leading, string text, strin return new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlEntity((InternalSyntax.CSharpSyntaxNode)leading.Node, text, value, (InternalSyntax.CSharpSyntaxNode)trailing.Node)); } + public static DocumentationCommentTriviaSyntax DocumentationComment(params XmlNodeSyntax[] content) + { + return DocumentationCommentTrivia(SyntaxKind.SingleLineDocumentationCommentTrivia, List(content)) + .WithLeadingTrivia(DocumentationCommentExterior("/// ")) + .WithTrailingTrivia(EndOfLine(Environment.NewLine)); + } + + public static XmlElementSyntax XmlSummaryElement(params XmlNodeSyntax[] content) + { + return XmlSummaryElement(List(content)); + } + + public static XmlElementSyntax XmlSummaryElement(SyntaxList content) + { + return XmlMultiLineElement("summary", content); + } + + public static XmlEmptyElementSyntax XmlSeeElement(CrefSyntax cref) + { + return XmlEmptyElement("see").AddAttributes(XmlCrefAttribute(cref)); + } + + public static XmlEmptyElementSyntax XmlSeeAlsoElement(CrefSyntax cref) + { + return XmlEmptyElement("seealso").AddAttributes(XmlCrefAttribute(cref)); + } + + public static XmlElementSyntax XmlSeeAlsoElement(Uri linkAddress, SyntaxList linkText) + { + XmlElementSyntax element = XmlElement("seealso", linkText); + return element.WithStartTag(element.StartTag.AddAttributes(XmlTextAttribute("href", linkAddress.ToString()))); + } + + public static XmlEmptyElementSyntax XmlThreadSafetyElement() + { + return XmlThreadSafetyElement(true, false); + } + + public static XmlEmptyElementSyntax XmlThreadSafetyElement(bool @static, bool instance) + { + return XmlEmptyElement("threadsafety").AddAttributes( + XmlTextAttribute("static", @static.ToString().ToLowerInvariant()), + XmlTextAttribute("instance", instance.ToString().ToLowerInvariant())); + } + + public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) + { + return XmlNameAttribute( + XmlName("name"), + Token(SyntaxKind.DoubleQuoteToken), + parameterName, + Token(SyntaxKind.DoubleQuoteToken)) + .WithLeadingTrivia(Whitespace(" ")); + } + + public static XmlEmptyElementSyntax PreliminaryElement() + { + return XmlEmptyElement("preliminary"); + } + + public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref) + { + return XmlCrefAttribute(cref, SyntaxKind.DoubleQuoteToken); + } + + public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref, SyntaxKind quoteKind) + { + cref = cref.ReplaceTokens(cref.DescendantTokens(), XmlReplaceBracketTokens); + return XmlCrefAttribute( + XmlName("cref"), + Token(quoteKind), + cref, + Token(quoteKind)) + .WithLeadingTrivia(Whitespace(" ")); + } + + public static XmlElementSyntax XmlRemarksElement(params XmlNodeSyntax[] content) + { + return XmlRemarksElement(List(content)); + } + + public static XmlElementSyntax XmlRemarksElement(SyntaxList content) + { + return XmlMultiLineElement("remarks", content); + } + + public static XmlElementSyntax XmlReturnsElement(params XmlNodeSyntax[] content) + { + return XmlReturnsElement(List(content)); + } + + public static XmlElementSyntax XmlReturnsElement(SyntaxList content) + { + return XmlMultiLineElement("returns", content); + } + + public static XmlElementSyntax XmlValueElement(params XmlNodeSyntax[] content) + { + return XmlValueElement(List(content)); + } + + public static XmlElementSyntax XmlValueElement(SyntaxList content) + { + return XmlMultiLineElement("value", content); + } + + public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, params XmlNodeSyntax[] content) + { + return ExceptionElement(cref, List(content)); + } + + public static XmlElementSyntax ExceptionElement(CrefSyntax cref, SyntaxList content) + { + XmlElementSyntax element = XmlElement("exception", content); + return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); + } + + public static XmlElementSyntax XmlParaElement(params XmlNodeSyntax[] content) + { + return XmlParaElement(List(content)); + } + + public static XmlElementSyntax XmlParaElement(SyntaxList content) + { + return XmlElement("para", content); + } + + public static XmlElementSyntax XmlParamElement(string parameterName, params XmlNodeSyntax[] content) + { + return XmlParamElement(parameterName, List(content)); + } + + public static XmlElementSyntax XmlParamElement(string parameterName, SyntaxList content) + { + XmlElementSyntax element = XmlElement("param", content); + return element.WithStartTag(element.StartTag.AddAttributes(XmlNameAttribute(parameterName))); + } + + public static XmlEmptyElementSyntax XmlParamRefElement(string parameterName) + { + return XmlEmptyElement("paramref").AddAttributes(XmlNameAttribute(parameterName)); + } + + public static XmlEmptyElementSyntax XmlNullKeywordElement() + { + return XmlKeywordElement("null"); + } + + private static XmlEmptyElementSyntax XmlKeywordElement(string keyword) + { + return XmlEmptyElement("see").AddAttributes( + XmlTextAttribute("langword", keyword)); + } + + public static XmlElementSyntax XmlPlaceholderElement(params XmlNodeSyntax[] content) + { + return XmlPlaceholderElement(List(content)); + } + + public static XmlElementSyntax XmlPlaceholderElement(SyntaxList content) + { + return XmlElement("placeholder", content); + } + + public static XmlEmptyElementSyntax XmlEmptyElement(string localName) + { + return XmlEmptyElement(XmlName(localName)); + } + + public static XmlElementSyntax XmlElement(string localName, SyntaxList content) + { + return XmlElement(XmlName(localName), content); + } + + public static XmlElementSyntax XmlElement(XmlNameSyntax name, SyntaxList content) + { + return XmlElement( + XmlElementStartTag(name), + content, + XmlElementEndTag(name)); + } + + public static XmlTextAttributeSyntax XmlTextAttribute(string name, string value) + { + return XmlTextAttribute(name, XmlTextLiteral(value)); + } + + public static XmlTextAttributeSyntax XmlTextAttribute(string name, params SyntaxToken[] textTokens) + { + return XmlTextAttribute(XmlName(name), SyntaxKind.DoubleQuoteToken, TokenList(textTokens)); + } + + public static XmlTextAttributeSyntax XmlTextAttribute(string name, SyntaxKind quoteKind, SyntaxTokenList textTokens) + { + return XmlTextAttribute(XmlName(name), SyntaxKind.DoubleQuoteToken, textTokens); + } + + public static XmlTextAttributeSyntax XmlTextAttribute(XmlNameSyntax name, SyntaxKind quoteKind, SyntaxTokenList textTokens) + { + return XmlTextAttribute( + name, + Token(quoteKind), + textTokens, + Token(quoteKind)) + .WithLeadingTrivia(Whitespace(" ")); + } + + public static XmlElementSyntax XmlMultiLineElement(string localName, SyntaxList content) + { + return XmlMultiLineElement(XmlName(localName), content); + } + + public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxList content) + { + return XmlElement( + XmlElementStartTag(name), + content.Insert(0, XmlNewLine()).Add(XmlNewLine()), + XmlElementEndTag(name)); + } + + public static XmlTextSyntax XmlNewLine() + { + return XmlText(XmlTextNewLine()); + } + + public static SyntaxToken XmlTextNewLine() + { + return XmlTextNewLine(true); + } + + public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) + { + SyntaxToken token = XmlTextNewLine( + TriviaList(), + Environment.NewLine, + Environment.NewLine, + TriviaList()); + + if (continueXmlDocumentationComment) + token = token.WithTrailingTrivia(DocumentationCommentExterior("/// ")); + + return token; + } + + public static XmlTextSyntax XmlText(string value) + { + return XmlText(XmlTextLiteral(value)); + } + + public static XmlTextSyntax XmlText(params SyntaxToken[] textTokens) + { + return XmlText(TokenList(textTokens)); + } + + public static SyntaxToken XmlTextLiteral(string value) + { + // TODO: [RobinSedlaczek] It is no compiler hot path here I think. But the contribution guide + // states to avoid LINQ (https://github.com/dotnet/roslyn/wiki/Contributing-Code). With + // XText we have a reference to System.Xml.Linq. Isn't this rule valid here? + string encoded = new XText(value).ToString(); + return XmlTextLiteral( + TriviaList(), + encoded, + value, + TriviaList()); + } + + private static SyntaxToken XmlReplaceBracketTokens(SyntaxToken originalToken, SyntaxToken rewrittenToken) + { + if (rewrittenToken.IsKind(SyntaxKind.LessThanToken) && string.Equals("<", rewrittenToken.Text, StringComparison.Ordinal)) + return Token(rewrittenToken.LeadingTrivia, SyntaxKind.LessThanToken, "{", rewrittenToken.ValueText, rewrittenToken.TrailingTrivia); + + if (rewrittenToken.IsKind(SyntaxKind.GreaterThanToken) && string.Equals(">", rewrittenToken.Text, StringComparison.Ordinal)) + return Token(rewrittenToken.LeadingTrivia, SyntaxKind.GreaterThanToken, "}", rewrittenToken.ValueText, rewrittenToken.TrailingTrivia); + + return rewrittenToken; + } + /// /// Creates a trivia with kind DocumentationCommentExteriorTrivia. /// diff --git a/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs b/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs index 875c97676aa1f..f3ff2552d8ce4 100644 --- a/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs @@ -352,6 +352,33 @@ public void TestLiteralToStringDifferentCulture() Thread.CurrentThread.CurrentCulture = culture; } + [Fact] + public void TestDocumentationComment() + { + var expected = @"/// +/// This class provides extension methods for the class. +/// +/// +/// "; + + Symbol declaringType = null; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods for the "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)))), + SyntaxFactory.XmlText(" class.")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlThreadSafetyElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.PreliminaryElement()); + + var actual = documentationComment.ToString(); + + Assert.Equal(expected, actual); + } + private static void CheckLiteralToString(dynamic value, string expected) { var literal = SyntaxFactory.Literal(value); From 73e775f47d0a606d7f74f21312e09a1b3ab375bf Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Fri, 13 Nov 2015 05:54:23 +0100 Subject: [PATCH 02/13] Adapt naming. Add methods to SyntaxFactory to create permission and exmaple elements in xml documentation comments. Add some unit tests. --- .../CSharp/Portable/PublicAPI.Unshipped.txt | 8 +- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 28 ++- .../LexicalAndXml/XmlDocCommentTests.cs | 215 ++++++++++++++++++ 3 files changed, 246 insertions(+), 5 deletions(-) diff --git a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt index c9c6f60fb3f55..f72851a09510f 100644 --- a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt @@ -51,10 +51,8 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this M static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this Microsoft.CodeAnalysis.SyntaxTriviaList list, string indentation = " ", string eol = "\r\n", bool elasticTrivia = false) -> Microsoft.CodeAnalysis.SyntaxTriviaList static Microsoft.CodeAnalysis.CSharp.SyntaxExtensions.NormalizeWhitespace(this Microsoft.CodeAnalysis.SyntaxTriviaList list, string indentation, bool elasticTrivia) -> Microsoft.CodeAnalysis.SyntaxTriviaList static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.DocumentationComment(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.DocumentationCommentTriviaSyntax -static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ExceptionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.LoadDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken file, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.LoadDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken hashToken, Microsoft.CodeAnalysis.SyntaxToken loadKeyword, Microsoft.CodeAnalysis.SyntaxToken file, Microsoft.CodeAnalysis.SyntaxToken endOfDirectiveToken, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax -static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.PreliminaryElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ShebangDirectiveTrivia(Microsoft.CodeAnalysis.SyntaxToken hashToken, Microsoft.CodeAnalysis.SyntaxToken exclamationToken, Microsoft.CodeAnalysis.SyntaxToken endOfDirectiveToken, bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ShebangDirectiveTrivia(bool isActive) -> Microsoft.CodeAnalysis.CSharp.Syntax.ShebangDirectiveTriviaSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlCrefAttribute(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlCrefAttributeSyntax @@ -62,6 +60,9 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlCrefAttribute(Microsoft.Co static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlElement(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlElement(string localName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlEmptyElement(string localName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExampleElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExampleElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExceptionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExceptionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(string localName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax @@ -73,8 +74,11 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParaElement(params Microso static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamElement(string parameterName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamElement(string parameterName, params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParamRefElement(string parameterName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPermissionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPermissionElement(Microsoft.CodeAnalysis.CSharp.Syntax.CrefSyntax cref, params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPlaceholderElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPlaceholderElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlPreliminaryElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlRemarksElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlRemarksElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlReturnsElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index bd8c483eadccd..4d3e3ae44d062 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -719,7 +719,7 @@ public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) .WithLeadingTrivia(Whitespace(" ")); } - public static XmlEmptyElementSyntax PreliminaryElement() + public static XmlEmptyElementSyntax XmlPreliminaryElement() { return XmlEmptyElement("preliminary"); } @@ -772,15 +772,37 @@ public static XmlElementSyntax XmlValueElement(SyntaxList content public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, params XmlNodeSyntax[] content) { - return ExceptionElement(cref, List(content)); + return XmlExceptionElement(cref, List(content)); } - public static XmlElementSyntax ExceptionElement(CrefSyntax cref, SyntaxList content) + public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, SyntaxList content) { XmlElementSyntax element = XmlElement("exception", content); return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); } + public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, params XmlNodeSyntax[] content) + { + return XmlPermissionElement(cref, List(content)); + } + + public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, SyntaxList content) + { + XmlElementSyntax element = XmlElement("permission", content); + return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); + } + + public static XmlElementSyntax XmlExampleElement(params XmlNodeSyntax[] content) + { + return XmlExampleElement(List(content)); + } + + public static XmlElementSyntax XmlExampleElement(SyntaxList content) + { + XmlElementSyntax element = XmlElement("example", content); + return element.WithStartTag(element.StartTag); + } + public static XmlElementSyntax XmlParaElement(params XmlNodeSyntax[] content) { return XmlParaElement(List(content)); diff --git a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs index c041822c263bc..b092eb39b0a54 100644 --- a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs @@ -2861,7 +2861,222 @@ public class Program Diagnostic(ErrorCode.WRN_XMLParseError, " ")); } + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestDocumentationComment() + { + var expected = @"/// +/// This class provides extension methods for the class. +/// +/// +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods for the "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText(" class.")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlThreadSafetyElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlPreliminaryElement()); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlSummaryElement() + { + var expected = @"/// +/// This class provides extension methods. +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlSeeElementAndXmlSeeAlsoElement() + { + var expected = @"/// +/// This class provides extension methods for the class and the class. +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods for the "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText(" class and the "), + SyntaxFactory.XmlSeeAlsoElement( + SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName2"))), + SyntaxFactory.XmlText(" class."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlNewLineElement() + { + var expected = @"/// +/// This is a summary. +/// +/// +/// +/// +/// +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This is a summary.")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlRemarksElement()); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlParamAndParamRefElement() + { + var expected = @"/// +/// +/// +/// +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlParamRefElement("b")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlParamElement("a"), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlParamElement("b")); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlReturnsElement() + { + var expected = @"/// +/// +/// +/// +/// Returns a value. +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlReturnsElement( + SyntaxFactory.XmlText("Returns a value."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlRemarksElement() + { + var expected = @"/// +/// +/// +/// +/// Same as in class . +/// +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlRemarksElement( + SyntaxFactory.XmlText("Same as in class "), + SyntaxFactory.XmlSeeElement(SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText("."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlExceptionElement() + { + var expected = @"/// +/// +/// +/// This exception will be thrown if the object is in an invalid state when calling this method. +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlExceptionElement( + SyntaxFactory.TypeCref( + SyntaxFactory.ParseTypeName("InvalidOperationException")), + SyntaxFactory.XmlText("This exception will be thrown if the object is in an invalid state when calling this method."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + + [Fact] + [Trait("Feature", "Xml Documentation Comments")] + public void TestXmlPermissionElement() + { + var expected = @"/// +/// +/// +/// Needs MyPermission to execute. +"; + + DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlPermissionElement( + SyntaxFactory.TypeCref( + SyntaxFactory.ParseTypeName("MyPermission")), + SyntaxFactory.XmlText("Needs MyPermission to execute."))); + + var actual = documentationComment.ToFullString(); + + Assert.Equal(expected, actual); + } + #region Xml Test helpers + /// /// Verifies that the errors on the given CSharpSyntaxNode match the expected error codes and types /// From 5810e13796c9612b2cf7b19199cb7e2ec9a52f2a Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Fri, 13 Nov 2015 07:45:49 +0100 Subject: [PATCH 03/13] Document new public API methods in SyntaxFactory. --- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 4d3e3ae44d062..8d827b8a7edd4 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -664,6 +664,13 @@ public static SyntaxToken XmlEntity(SyntaxTriviaList leading, string text, strin return new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlEntity((InternalSyntax.CSharpSyntaxNode)leading.Node, text, value, (InternalSyntax.CSharpSyntaxNode)trailing.Node)); } + /// + /// Creates an xml documentation comment that abstracts xml syntax creation. + /// + /// + /// A list of xml node syntax that will be the content within the xml documentation comment + /// (e.g. a summary element, a returns element, exception element and so on). + /// public static DocumentationCommentTriviaSyntax DocumentationComment(params XmlNodeSyntax[] content) { return DocumentationCommentTrivia(SyntaxKind.SingleLineDocumentationCommentTrivia, List(content)) @@ -671,37 +678,66 @@ public static DocumentationCommentTriviaSyntax DocumentationComment(params XmlNo .WithTrailingTrivia(EndOfLine(Environment.NewLine)); } + /// + /// Creates a summary element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the summary element. public static XmlElementSyntax XmlSummaryElement(params XmlNodeSyntax[] content) { return XmlSummaryElement(List(content)); } + /// + /// Creates a summary element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the summary element. public static XmlElementSyntax XmlSummaryElement(SyntaxList content) { return XmlMultiLineElement("summary", content); } + /// + /// Creates a see element within an xml documentation comment. + /// + /// A cref syntax node that points to the referenced item (e.g. a class, struct). public static XmlEmptyElementSyntax XmlSeeElement(CrefSyntax cref) { return XmlEmptyElement("see").AddAttributes(XmlCrefAttribute(cref)); } + /// + /// Creates a seealso element within an xml documentation comment. + /// + /// A cref syntax node that points to the referenced item (e.g. a class, struct). public static XmlEmptyElementSyntax XmlSeeAlsoElement(CrefSyntax cref) { return XmlEmptyElement("seealso").AddAttributes(XmlCrefAttribute(cref)); } + /// + /// Creates a seealso element within an xml documentation comment. + /// + /// The uri of the referenced item. + /// A list of xml node syntax that will be used as the link text for the referenced item. public static XmlElementSyntax XmlSeeAlsoElement(Uri linkAddress, SyntaxList linkText) { XmlElementSyntax element = XmlElement("seealso", linkText); return element.WithStartTag(element.StartTag.AddAttributes(XmlTextAttribute("href", linkAddress.ToString()))); } + /// + /// Creates a threadsafty element within an xml documentation comment. + /// public static XmlEmptyElementSyntax XmlThreadSafetyElement() { return XmlThreadSafetyElement(true, false); } + /// + /// Creates a threadsafty element within an xml documentation comment. + /// + /// Indicates whether static member of this class are safe for multi-threaded operations. + /// Indicates whether members of instances of this type are safe for multi-threaded operations. public static XmlEmptyElementSyntax XmlThreadSafetyElement(bool @static, bool instance) { return XmlEmptyElement("threadsafety").AddAttributes( @@ -709,6 +745,10 @@ public static XmlEmptyElementSyntax XmlThreadSafetyElement(bool @static, bool in XmlTextAttribute("instance", instance.ToString().ToLowerInvariant())); } + /// + /// Creates a syntax node for a name attribute in a xml element within a xml documentation comment. + /// + /// The value of the name attribute. public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) { return XmlNameAttribute( @@ -719,16 +759,28 @@ public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) .WithLeadingTrivia(Whitespace(" ")); } + /// + /// Creates a syntax node for a priliminary element within a xml documentation comment. + /// public static XmlEmptyElementSyntax XmlPreliminaryElement() { return XmlEmptyElement("preliminary"); } + /// + /// Creates a syntax node for a cref attribute within a xml documentation comment. + /// + /// The used for the xml cref attribute syntax. public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref) { return XmlCrefAttribute(cref, SyntaxKind.DoubleQuoteToken); } + /// + /// Creates a syntax node for a cref attribute within a xml documentation comment. + /// + /// The used for the xml cref attribute syntax. + /// The kind of the quote for the referenced item in the cref attribute. public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref, SyntaxKind quoteKind) { cref = cref.ReplaceTokens(cref.DescendantTokens(), XmlReplaceBracketTokens); @@ -740,21 +792,37 @@ public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref, SyntaxKin .WithLeadingTrivia(Whitespace(" ")); } + /// + /// Creates a remarks element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the remarks element. public static XmlElementSyntax XmlRemarksElement(params XmlNodeSyntax[] content) { return XmlRemarksElement(List(content)); } + /// + /// Creates a remarks element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the remarks element. public static XmlElementSyntax XmlRemarksElement(SyntaxList content) { return XmlMultiLineElement("remarks", content); } + /// + /// Creates a returns element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the returns element. public static XmlElementSyntax XmlReturnsElement(params XmlNodeSyntax[] content) { return XmlReturnsElement(List(content)); } + /// + /// Creates a returns element within an xml documentation comment. + /// + /// A list of xml node syntax that will be the content within the returns element. public static XmlElementSyntax XmlReturnsElement(SyntaxList content) { return XmlMultiLineElement("returns", content); From 1bf370c877a384f1c0e21c14d93559f873cf83fe Mon Sep 17 00:00:00 2001 From: robinsedlaczek Date: Fri, 13 Nov 2015 16:04:33 +0100 Subject: [PATCH 04/13] Remove unit test from incorrect class. --- .../Test/Syntax/Syntax/SyntaxFactoryTests.cs | 27 ------------------- 1 file changed, 27 deletions(-) diff --git a/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs b/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs index f3ff2552d8ce4..875c97676aa1f 100644 --- a/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/Syntax/SyntaxFactoryTests.cs @@ -352,33 +352,6 @@ public void TestLiteralToStringDifferentCulture() Thread.CurrentThread.CurrentCulture = culture; } - [Fact] - public void TestDocumentationComment() - { - var expected = @"/// -/// This class provides extension methods for the class. -/// -/// -/// "; - - Symbol declaringType = null; - - DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This class provides extension methods for the "), - SyntaxFactory.XmlSeeElement( - SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)))), - SyntaxFactory.XmlText(" class.")), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.XmlThreadSafetyElement(), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.PreliminaryElement()); - - var actual = documentationComment.ToString(); - - Assert.Equal(expected, actual); - } - private static void CheckLiteralToString(dynamic value, string expected) { var literal = SyntaxFactory.Literal(value); From 2240484fbded60d8c404f2bf6eab04bb2f727c77 Mon Sep 17 00:00:00 2001 From: robinsedlaczek Date: Fri, 13 Nov 2015 19:28:44 +0100 Subject: [PATCH 05/13] Add code documentation for new SyntaxFactory methods (for easier creation of xml documentation comment syntax). --- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 8d827b8a7edd4..6e457472d157c 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -828,106 +828,200 @@ public static XmlElementSyntax XmlReturnsElement(SyntaxList conte return XmlMultiLineElement("returns", content); } + /// + /// Creates the the syntax representation of an xml value element (e.g. for xml documentation comments). + /// + /// A list of xml syntax nodes that represents the content of the value element. public static XmlElementSyntax XmlValueElement(params XmlNodeSyntax[] content) { return XmlValueElement(List(content)); } + /// + /// Creates the the syntax representation of an xml value element (e.g. for xml documentation comments). + /// + /// A list of xml syntax nodes that represents the content of the value element. public static XmlElementSyntax XmlValueElement(SyntaxList content) { return XmlMultiLineElement("value", content); } + /// + /// Creates the syntax representation of an exception element within xml documentation comments. + /// + /// Syntax representation of the reference to the exception type. + /// A list of syntax nodes that represents the content of the exception element. public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, params XmlNodeSyntax[] content) { return XmlExceptionElement(cref, List(content)); } + /// + /// Creates the syntax representation of an exception element within xml documentation comments. + /// + /// Syntax representation of the reference to the exception type. + /// A list of syntax nodes that represents the content of the exception element. public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, SyntaxList content) { XmlElementSyntax element = XmlElement("exception", content); return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); } + /// + /// Creates the syntax representation of a permission element within xml documentation comments. + /// + /// Syntax representation of the reference to the permission type. + /// A list of syntax nodes that represents the content of the permission element. public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, params XmlNodeSyntax[] content) { return XmlPermissionElement(cref, List(content)); } + /// + /// Creates the syntax representation of a permission element within xml documentation comments. + /// + /// Syntax representation of the reference to the permission type. + /// A list of syntax nodes that represents the content of the permission element. public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, SyntaxList content) { XmlElementSyntax element = XmlElement("permission", content); return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); } + /// + /// Creates the syntax representation of an example element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the example element. public static XmlElementSyntax XmlExampleElement(params XmlNodeSyntax[] content) { return XmlExampleElement(List(content)); } + /// + /// Creates the syntax representation of an example element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the example element. public static XmlElementSyntax XmlExampleElement(SyntaxList content) { XmlElementSyntax element = XmlElement("example", content); return element.WithStartTag(element.StartTag); } + /// + /// Creates the syntax representation of a para element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the para element. public static XmlElementSyntax XmlParaElement(params XmlNodeSyntax[] content) { return XmlParaElement(List(content)); } + /// + /// Creates the syntax representation of a para element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the para element. public static XmlElementSyntax XmlParaElement(SyntaxList content) { return XmlElement("para", content); } + /// + /// Creates the syntax representation of a param element within xml documentation comments (e.g. for + /// documentation of method parameters). + /// + /// The name of the parameter. + /// A list of syntax nodes that represents the content of the param element (e.g. + /// the description and meaning of the parameter). public static XmlElementSyntax XmlParamElement(string parameterName, params XmlNodeSyntax[] content) { return XmlParamElement(parameterName, List(content)); } + /// + /// Creates the syntax representation of a param element within xml documentation comments (e.g. for + /// documentation of method parameters). + /// + /// The name of the parameter. + /// A list of syntax nodes that represents the content of the param element (e.g. + /// the description and meaning of the parameter). public static XmlElementSyntax XmlParamElement(string parameterName, SyntaxList content) { XmlElementSyntax element = XmlElement("param", content); return element.WithStartTag(element.StartTag.AddAttributes(XmlNameAttribute(parameterName))); } + /// + /// Creates the syntax representation of a paramref element within xml documentation comments (e.g. for + /// referencing particular parameters of a method). + /// + /// The name of the referenced parameter. public static XmlEmptyElementSyntax XmlParamRefElement(string parameterName) { return XmlEmptyElement("paramref").AddAttributes(XmlNameAttribute(parameterName)); } + /// + /// Creates the syntax representation of a see element within xml documentation comments, + /// that points to the 'null' language keyword. + /// public static XmlEmptyElementSyntax XmlNullKeywordElement() { return XmlKeywordElement("null"); } + /// + /// Creates the syntax representation of a see element within xml documentation comments, + /// that points to a language keyword. + /// + /// The language keyword to which the see element points to. private static XmlEmptyElementSyntax XmlKeywordElement(string keyword) { return XmlEmptyElement("see").AddAttributes( XmlTextAttribute("langword", keyword)); } + /// + /// Creates the syntax representation of a placeholder element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the placeholder element. public static XmlElementSyntax XmlPlaceholderElement(params XmlNodeSyntax[] content) { return XmlPlaceholderElement(List(content)); } + /// + /// Creates the syntax representation of a placeholder element within xml documentation comments. + /// + /// A list of syntax nodes that represents the content of the placeholder element. public static XmlElementSyntax XmlPlaceholderElement(SyntaxList content) { return XmlElement("placeholder", content); } + /// + /// Creates the syntax representation of a named empty xml element within xml documentation comments. + /// + /// The name of the empty xml element. public static XmlEmptyElementSyntax XmlEmptyElement(string localName) { return XmlEmptyElement(XmlName(localName)); } + /// + /// Creates the syntax representation of a named xml element within xml documentation comments. + /// + /// The name of the empty xml element. + /// A list of syntax nodes that represents the content of the xml element. public static XmlElementSyntax XmlElement(string localName, SyntaxList content) { return XmlElement(XmlName(localName), content); } + /// + /// Creates the syntax representation of a named xml element within xml documentation comments. + /// + /// The name of the empty xml element. + /// A list of syntax nodes that represents the content of the xml element. public static XmlElementSyntax XmlElement(XmlNameSyntax name, SyntaxList content) { return XmlElement( @@ -936,21 +1030,43 @@ public static XmlElementSyntax XmlElement(XmlNameSyntax name, SyntaxList + /// Creates the syntax representation of an xml text attribute. + /// + /// The name of the xml text attribute. + /// The value of the xml text attribute. public static XmlTextAttributeSyntax XmlTextAttribute(string name, string value) { return XmlTextAttribute(name, XmlTextLiteral(value)); } + /// + /// Creates the syntax representation of an xml text attribute. + /// + /// The name of the xml text attribute. + /// A list of tokens used for the value of the xml text attribute. public static XmlTextAttributeSyntax XmlTextAttribute(string name, params SyntaxToken[] textTokens) { return XmlTextAttribute(XmlName(name), SyntaxKind.DoubleQuoteToken, TokenList(textTokens)); } + /// + /// Creates the syntax representation of an xml text attribute. + /// + /// The name of the xml text attribute. + /// The kind of the quote token to be used to quote the value (e.g. " or '). + /// A list of tokens used for the value of the xml text attribute. public static XmlTextAttributeSyntax XmlTextAttribute(string name, SyntaxKind quoteKind, SyntaxTokenList textTokens) { return XmlTextAttribute(XmlName(name), SyntaxKind.DoubleQuoteToken, textTokens); } + /// + /// Creates the syntax representation of an xml text attribute. + /// + /// The name of the xml text attribute. + /// The kind of the quote token to be used to quote the value (e.g. " or '). + /// A list of tokens used for the value of the xml text attribute. public static XmlTextAttributeSyntax XmlTextAttribute(XmlNameSyntax name, SyntaxKind quoteKind, SyntaxTokenList textTokens) { return XmlTextAttribute( @@ -961,11 +1077,21 @@ public static XmlTextAttributeSyntax XmlTextAttribute(XmlNameSyntax name, Syntax .WithLeadingTrivia(Whitespace(" ")); } + /// + /// Creates the syntax representation of an xml element that spans multiple text lines. + /// + /// The name of the xml element. + /// A list of syntax nodes that represents the content of the xml multi line element. public static XmlElementSyntax XmlMultiLineElement(string localName, SyntaxList content) { return XmlMultiLineElement(XmlName(localName), content); } + /// + /// Creates the syntax representation of an xml element that spans multiple text lines. + /// + /// The name of the xml element. + /// A list of syntax nodes that represents the content of the xml multi line element. public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxList content) { return XmlElement( @@ -974,16 +1100,30 @@ public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxLis XmlElementEndTag(name)); } + /// + /// Creates the syntax representation of an xml text that contains a newline token with a documentation comment + /// exterior trivia at the end (continued documentation comment). + /// public static XmlTextSyntax XmlNewLine() { return XmlText(XmlTextNewLine()); } + /// + /// Creates the syntax representation of an xml newline token with a documentation comment exterior trivia at + /// the end (continued documentation comment). + /// public static SyntaxToken XmlTextNewLine() { return XmlTextNewLine(true); } + /// + /// Creates the syntax representation of an xml newline token for xml documentation comments. + /// + /// + /// If set to true, a documentation comment exterior token will be added to the trailing trivia + /// of the new token. public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) { SyntaxToken token = XmlTextNewLine( @@ -998,16 +1138,28 @@ public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) return token; } + /// + /// Generates the syntax representation of a xml text node (e.g. for xml documentation comments). + /// + /// The string literal used as the text of the xml text node. public static XmlTextSyntax XmlText(string value) { return XmlText(XmlTextLiteral(value)); } + /// + /// Generates the syntax representation of a xml text node (e.g. for xml documentation comments). + /// + /// A list of text tokens used as the text of the xml text node. public static XmlTextSyntax XmlText(params SyntaxToken[] textTokens) { return XmlText(TokenList(textTokens)); } + /// + /// Generates the syntax representation of an xml text literal. + /// + /// The text used within the xml text literal. public static SyntaxToken XmlTextLiteral(string value) { // TODO: [RobinSedlaczek] It is no compiler hot path here I think. But the contribution guide @@ -1021,6 +1173,12 @@ public static SyntaxToken XmlTextLiteral(string value) TriviaList()); } + /// + /// Helper method that replaces less-than and greater-than characters with brackets. + /// + /// The original token that is to be replaced. + /// The new rewritten token. + /// Returns the new rewritten token with replaced characters. private static SyntaxToken XmlReplaceBracketTokens(SyntaxToken originalToken, SyntaxToken rewrittenToken) { if (rewrittenToken.IsKind(SyntaxKind.LessThanToken) && string.Equals("<", rewrittenToken.Text, StringComparison.Ordinal)) From e62ae898b32e373300de9414664b6bb09ec5bb04 Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Sun, 6 Dec 2015 17:02:05 +0100 Subject: [PATCH 06/13] Implement overloads for documentation comment trivias that uses elastic trivia. --- .../CSharp/Portable/PublicAPI.Unshipped.txt | 2 ++ .../CSharp/Portable/Syntax/SyntaxFactory.cs | 29 +++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt index f72851a09510f..99d8ad01b1d29 100644 --- a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt @@ -94,9 +94,11 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(Microsoft.Co static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, Microsoft.CodeAnalysis.CSharp.SyntaxKind quoteKind, Microsoft.CodeAnalysis.SyntaxTokenList textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, params Microsoft.CodeAnalysis.SyntaxToken[] textTokens) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, string value) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string text, string value) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string value) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(bool continueXmlDocumentationComment) -> Microsoft.CodeAnalysis.SyntaxToken +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(string text, bool continueXmlDocumentationComment) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement(bool static, bool instance) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlValueElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 6e457472d157c..447489610ef95 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -1138,6 +1138,24 @@ public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) return token; } + /// + /// Creates the syntax representation of an xml newline token for xml documentation comments. + /// + /// The raw text within the new line. + /// + /// If set to true, a documentation comment exterior token will be added to the trailing trivia + /// of the new token. + public static SyntaxToken XmlTextNewLine(string text, bool continueXmlDocumentationComment) + { + var value = Environment.NewLine; + var token = new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextNewLine((InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode, text, value, (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode)); + + if (continueXmlDocumentationComment) + token = token.WithTrailingTrivia(DocumentationCommentExterior("/// ")); + + return token; + } + /// /// Generates the syntax representation of a xml text node (e.g. for xml documentation comments). /// @@ -1166,6 +1184,7 @@ public static SyntaxToken XmlTextLiteral(string value) // states to avoid LINQ (https://github.com/dotnet/roslyn/wiki/Contributing-Code). With // XText we have a reference to System.Xml.Linq. Isn't this rule valid here? string encoded = new XText(value).ToString(); + return XmlTextLiteral( TriviaList(), encoded, @@ -1173,6 +1192,16 @@ public static SyntaxToken XmlTextLiteral(string value) TriviaList()); } + /// + /// Generates the syntax representation of an xml text literal. + /// + /// The raw text of the literal. + /// The text used within the xml text literal. + public static SyntaxToken XmlTextLiteral(string text, string value) + { + return new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextLiteral((InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode, text, value, (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode)); + } + /// /// Helper method that replaces less-than and greater-than characters with brackets. /// From 2eb1c44d885e93814c815077a0eabb1bdfecb3ec Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Wed, 9 Dec 2015 05:29:12 +0100 Subject: [PATCH 07/13] Implement Visual Basic syntax factory methods (and unit tests) for creating xml documentation comments. Use elastic trivias when creating syntax token (in C# and VB SyntaxFactory). Use xml names from DocumentationCommentXmlNames class. --- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 47 +- .../DocumentationCommentXmlNames.cs | 8 +- .../Portable/PublicAPI.Unshipped.txt | 47 +- .../Portable/Syntax/SyntaxFactory.vb | 469 ++++++++++++++++++ .../Test/Syntax/Parser/XmlDocComments.vb | 219 ++++++++ 5 files changed, 765 insertions(+), 25 deletions(-) diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 447489610ef95..f0b0d827d1a0d 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -10,6 +10,7 @@ using Microsoft.CodeAnalysis.Text; using InternalSyntax = Microsoft.CodeAnalysis.CSharp.Syntax.InternalSyntax; using System.Xml.Linq; +using Roslyn.Utilities; namespace Microsoft.CodeAnalysis.CSharp { @@ -693,7 +694,7 @@ public static XmlElementSyntax XmlSummaryElement(params XmlNodeSyntax[] content) /// A list of xml node syntax that will be the content within the summary element. public static XmlElementSyntax XmlSummaryElement(SyntaxList content) { - return XmlMultiLineElement("summary", content); + return XmlMultiLineElement(DocumentationCommentXmlNames.SummaryElementName, content); } /// @@ -702,7 +703,7 @@ public static XmlElementSyntax XmlSummaryElement(SyntaxList conte /// A cref syntax node that points to the referenced item (e.g. a class, struct). public static XmlEmptyElementSyntax XmlSeeElement(CrefSyntax cref) { - return XmlEmptyElement("see").AddAttributes(XmlCrefAttribute(cref)); + return XmlEmptyElement(DocumentationCommentXmlNames.SeeElementName).AddAttributes(XmlCrefAttribute(cref)); } /// @@ -711,7 +712,7 @@ public static XmlEmptyElementSyntax XmlSeeElement(CrefSyntax cref) /// A cref syntax node that points to the referenced item (e.g. a class, struct). public static XmlEmptyElementSyntax XmlSeeAlsoElement(CrefSyntax cref) { - return XmlEmptyElement("seealso").AddAttributes(XmlCrefAttribute(cref)); + return XmlEmptyElement(DocumentationCommentXmlNames.SeeAlsoElementName).AddAttributes(XmlCrefAttribute(cref)); } /// @@ -721,8 +722,8 @@ public static XmlEmptyElementSyntax XmlSeeAlsoElement(CrefSyntax cref) /// A list of xml node syntax that will be used as the link text for the referenced item. public static XmlElementSyntax XmlSeeAlsoElement(Uri linkAddress, SyntaxList linkText) { - XmlElementSyntax element = XmlElement("seealso", linkText); - return element.WithStartTag(element.StartTag.AddAttributes(XmlTextAttribute("href", linkAddress.ToString()))); + XmlElementSyntax element = XmlElement(DocumentationCommentXmlNames.SeeAlsoElementName, linkText); + return element.WithStartTag(element.StartTag.AddAttributes(XmlTextAttribute(DocumentationCommentXmlNames.CrefAttributeName, linkAddress.ToString()))); } /// @@ -740,9 +741,9 @@ public static XmlEmptyElementSyntax XmlThreadSafetyElement() /// Indicates whether members of instances of this type are safe for multi-threaded operations. public static XmlEmptyElementSyntax XmlThreadSafetyElement(bool @static, bool instance) { - return XmlEmptyElement("threadsafety").AddAttributes( - XmlTextAttribute("static", @static.ToString().ToLowerInvariant()), - XmlTextAttribute("instance", instance.ToString().ToLowerInvariant())); + return XmlEmptyElement(DocumentationCommentXmlNames.ThreadSafetyElementName).AddAttributes( + XmlTextAttribute(DocumentationCommentXmlNames.StaticAttributeName, @static.ToString().ToLowerInvariant()), + XmlTextAttribute(DocumentationCommentXmlNames.InstanceAttributeName, instance.ToString().ToLowerInvariant())); } /// @@ -752,7 +753,7 @@ public static XmlEmptyElementSyntax XmlThreadSafetyElement(bool @static, bool in public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) { return XmlNameAttribute( - XmlName("name"), + XmlName(DocumentationCommentXmlNames.NameAttributeName), Token(SyntaxKind.DoubleQuoteToken), parameterName, Token(SyntaxKind.DoubleQuoteToken)) @@ -764,7 +765,7 @@ public static XmlNameAttributeSyntax XmlNameAttribute(string parameterName) /// public static XmlEmptyElementSyntax XmlPreliminaryElement() { - return XmlEmptyElement("preliminary"); + return XmlEmptyElement(DocumentationCommentXmlNames.PreliminaryElementName); } /// @@ -785,7 +786,7 @@ public static XmlCrefAttributeSyntax XmlCrefAttribute(CrefSyntax cref, SyntaxKin { cref = cref.ReplaceTokens(cref.DescendantTokens(), XmlReplaceBracketTokens); return XmlCrefAttribute( - XmlName("cref"), + XmlName(DocumentationCommentXmlNames.CrefAttributeName), Token(quoteKind), cref, Token(quoteKind)) @@ -807,7 +808,7 @@ public static XmlElementSyntax XmlRemarksElement(params XmlNodeSyntax[] content) /// A list of xml node syntax that will be the content within the remarks element. public static XmlElementSyntax XmlRemarksElement(SyntaxList content) { - return XmlMultiLineElement("remarks", content); + return XmlMultiLineElement(DocumentationCommentXmlNames.RemarksElementName, content); } /// @@ -825,7 +826,7 @@ public static XmlElementSyntax XmlReturnsElement(params XmlNodeSyntax[] content) /// A list of xml node syntax that will be the content within the returns element. public static XmlElementSyntax XmlReturnsElement(SyntaxList content) { - return XmlMultiLineElement("returns", content); + return XmlMultiLineElement(DocumentationCommentXmlNames.ReturnsElementName, content); } /// @@ -843,7 +844,7 @@ public static XmlElementSyntax XmlValueElement(params XmlNodeSyntax[] content) /// A list of xml syntax nodes that represents the content of the value element. public static XmlElementSyntax XmlValueElement(SyntaxList content) { - return XmlMultiLineElement("value", content); + return XmlMultiLineElement(DocumentationCommentXmlNames.ValueElementName, content); } /// @@ -863,7 +864,7 @@ public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, params XmlNo /// A list of syntax nodes that represents the content of the exception element. public static XmlElementSyntax XmlExceptionElement(CrefSyntax cref, SyntaxList content) { - XmlElementSyntax element = XmlElement("exception", content); + XmlElementSyntax element = XmlElement(DocumentationCommentXmlNames.ExceptionElementName, content); return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); } @@ -884,7 +885,7 @@ public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, params XmlN /// A list of syntax nodes that represents the content of the permission element. public static XmlElementSyntax XmlPermissionElement(CrefSyntax cref, SyntaxList content) { - XmlElementSyntax element = XmlElement("permission", content); + XmlElementSyntax element = XmlElement(DocumentationCommentXmlNames.PermissionElementName, content); return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))); } @@ -903,7 +904,7 @@ public static XmlElementSyntax XmlExampleElement(params XmlNodeSyntax[] content) /// A list of syntax nodes that represents the content of the example element. public static XmlElementSyntax XmlExampleElement(SyntaxList content) { - XmlElementSyntax element = XmlElement("example", content); + XmlElementSyntax element = XmlElement(DocumentationCommentXmlNames.ExampleElementName, content); return element.WithStartTag(element.StartTag); } @@ -922,7 +923,7 @@ public static XmlElementSyntax XmlParaElement(params XmlNodeSyntax[] content) /// A list of syntax nodes that represents the content of the para element. public static XmlElementSyntax XmlParaElement(SyntaxList content) { - return XmlElement("para", content); + return XmlElement(DocumentationCommentXmlNames.ParaElementName, content); } /// @@ -946,7 +947,7 @@ public static XmlElementSyntax XmlParamElement(string parameterName, params XmlN /// the description and meaning of the parameter). public static XmlElementSyntax XmlParamElement(string parameterName, SyntaxList content) { - XmlElementSyntax element = XmlElement("param", content); + XmlElementSyntax element = XmlElement(DocumentationCommentXmlNames.ParameterElementName, content); return element.WithStartTag(element.StartTag.AddAttributes(XmlNameAttribute(parameterName))); } @@ -957,7 +958,7 @@ public static XmlElementSyntax XmlParamElement(string parameterName, SyntaxList< /// The name of the referenced parameter. public static XmlEmptyElementSyntax XmlParamRefElement(string parameterName) { - return XmlEmptyElement("paramref").AddAttributes(XmlNameAttribute(parameterName)); + return XmlEmptyElement(DocumentationCommentXmlNames.ParameterReferenceElementName).AddAttributes(XmlNameAttribute(parameterName)); } /// @@ -976,8 +977,8 @@ public static XmlEmptyElementSyntax XmlNullKeywordElement() /// The language keyword to which the see element points to. private static XmlEmptyElementSyntax XmlKeywordElement(string keyword) { - return XmlEmptyElement("see").AddAttributes( - XmlTextAttribute("langword", keyword)); + return XmlEmptyElement(DocumentationCommentXmlNames.SeeElementName).AddAttributes( + XmlTextAttribute(DocumentationCommentXmlNames.KeywordElementName, keyword)); } /// @@ -995,7 +996,7 @@ public static XmlElementSyntax XmlPlaceholderElement(params XmlNodeSyntax[] cont /// A list of syntax nodes that represents the content of the placeholder element. public static XmlElementSyntax XmlPlaceholderElement(SyntaxList content) { - return XmlElement("placeholder", content); + return XmlElement(DocumentationCommentXmlNames.PlaceholderElementName, content); } /// diff --git a/src/Compilers/Core/Portable/InternalUtilities/DocumentationCommentXmlNames.cs b/src/Compilers/Core/Portable/InternalUtilities/DocumentationCommentXmlNames.cs index 7b9fd2926945d..cd4bef7a76a4a 100644 --- a/src/Compilers/Core/Portable/InternalUtilities/DocumentationCommentXmlNames.cs +++ b/src/Compilers/Core/Portable/InternalUtilities/DocumentationCommentXmlNames.cs @@ -28,12 +28,18 @@ internal static class DocumentationCommentXmlNames public const string TypeParameterElementName = "typeparam"; public const string TypeParameterReferenceElementName = "typeparamref"; public const string ValueElementName = "value"; - + public const string ThreadSafetyElementName = "threadsafety"; + public const string PreliminaryElementName = "preliminary"; + public const string KeywordElementName = "langword"; + public const string PlaceholderElementName = "placeholder"; + public const string CrefAttributeName = "cref"; public const string NameAttributeName = "name"; public const string FileAttributeName = "file"; public const string PathAttributeName = "path"; public const string TypeAttributeName = "type"; + public const string StaticAttributeName = "static"; + public const string InstanceAttributeName = "instance"; public static bool ElementEquals(string name1, string name2, bool fromVb = false) { diff --git a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt index 01f06035bbb3f..34584c503aa48 100644 --- a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt @@ -13,4 +13,49 @@ Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions.New(outputKind Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions.WithDeterministic(deterministic As Boolean) -> Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions.WithReportSuppressedDiagnostics(value As Boolean) -> Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions Microsoft.CodeAnalysis.VisualBasic.VisualBasicParseOptions.WithKind(kind As Microsoft.CodeAnalysis.SourceCodeKind) -> Microsoft.CodeAnalysis.VisualBasic.VisualBasicParseOptions -Overrides Microsoft.CodeAnalysis.VisualBasic.VisualBasicParseOptions.CommonWithKind(kind As Microsoft.CodeAnalysis.SourceCodeKind) -> Microsoft.CodeAnalysis.ParseOptions \ No newline at end of file +Overrides Microsoft.CodeAnalysis.VisualBasic.VisualBasicParseOptions.CommonWithKind(kind As Microsoft.CodeAnalysis.SourceCodeKind) -> Microsoft.CodeAnalysis.ParseOptions +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.DocumentationComment(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.DocumentationCommentTriviaSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlCrefAttribute(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlCrefAttributeSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlCrefAttribute(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax, quoteKind As Microsoft.CodeAnalysis.VisualBasic.SyntaxKind) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlCrefAttributeSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlElement(localName As String, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlElement(name As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNameSyntax, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlEmptyElement(localName As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlExampleElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlExampleElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlExceptionElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax, ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlExceptionElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlMultiLineElement(localName As String, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlMultiLineElement(name As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNameSyntax, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNameAttribute(parameterName As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNameAttributeSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNewLine() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNullKeywordElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParaElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParaElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParamElement(parameterName As String, ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParamElement(parameterName As String, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParamRefElement(parameterName As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlPermissionElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax, ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlPermissionElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlPlaceholderElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlPlaceholderElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlPreliminaryElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlRemarksElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlRemarksElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlReturnsElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlReturnsElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlSeeAlsoElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlSeeAlsoElement(linkAddress As System.Uri, linkText As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlSeeElement(cref As Microsoft.CodeAnalysis.VisualBasic.Syntax.CrefReferenceSyntax) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlSummaryElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlSummaryElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlText(ParamArray textTokens As Microsoft.CodeAnalysis.SyntaxToken()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlText(value As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(text As String, value As String) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(value As String) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(continueXmlDocumentationComment As Boolean) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(leading As Microsoft.CodeAnalysis.SyntaxTriviaList, text As String, value As String, trailing As Microsoft.CodeAnalysis.SyntaxTriviaList) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlThreadSafetyElement(static As Boolean, instance As Boolean) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlValueElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlValueElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax \ No newline at end of file diff --git a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb index 71a67c3c3b0b9..832a92823de20 100644 --- a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb +++ b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb @@ -1,5 +1,6 @@ ' Copyright (c) Microsoft. All Rights Reserved. Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. +Imports System.Xml.Linq Imports Microsoft.CodeAnalysis.VisualBasic.Syntax Imports VbObjectDisplay = Microsoft.CodeAnalysis.VisualBasic.ObjectDisplay.ObjectDisplay @@ -449,6 +450,474 @@ Namespace Microsoft.CodeAnalysis.VisualBasic End Select End Function + ''' + ''' Creates an xml documentation comment that abstracts xml syntax creation. + ''' + ''' + ''' A list of xml node syntax that will be the content within the xml documentation comment + ''' (e.g. a summary element, a returns element, exception element and so on). + ''' + Public Shared Function DocumentationComment(ParamArray content As XmlNodeSyntax()) As DocumentationCommentTriviaSyntax + Return DocumentationCommentTrivia(List(content)).WithLeadingTrivia(DocumentationCommentExteriorTrivia("''' ")).WithTrailingTrivia(EndOfLine(Environment.NewLine)) + End Function + + ''' + ''' Creates a summary element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the summary element. + Public Shared Function XmlSummaryElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlSummaryElement(List(content)) + End Function + + ''' + ''' Creates a summary element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the summary element. + Public Shared Function XmlSummaryElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlMultiLineElement(DocumentationCommentXmlNames.SummaryElementName, content) + End Function + + ''' + ''' Creates a see element within an xml documentation comment. + ''' + ''' A cref syntax node that points to the referenced item (e.g. a class, struct). + Public Shared Function XmlSeeElement(cref As CrefReferenceSyntax) As XmlEmptyElementSyntax + Return XmlEmptyElement(DocumentationCommentXmlNames.SeeElementName).AddAttributes(XmlCrefAttribute(cref)) + End Function + + ''' + ''' Creates a seealso element within an xml documentation comment. + ''' + ''' A cref syntax node that points to the referenced item (e.g. a class, struct). + Public Shared Function XmlSeeAlsoElement(cref As CrefReferenceSyntax) As XmlEmptyElementSyntax + Return XmlEmptyElement(DocumentationCommentXmlNames.SeeAlsoElementName).AddAttributes(XmlCrefAttribute(cref)) + End Function + + ''' + ''' Creates a seealso element within an xml documentation comment. + ''' + ''' The uri of the referenced item. + ''' A list of xml node syntax that will be used as the link text for the referenced item. + Public Shared Function XmlSeeAlsoElement(linkAddress As Uri, linkText As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Dim linkAddressString = linkAddress.ToString().ToLowerInvariant() + Dim element = XmlElement(DocumentationCommentXmlNames.SeeAlsoElementName, linkText) + + Return element.WithStartTag(element.StartTag.AddAttributes( + XmlAttribute( + XmlName(Nothing, XmlTextLiteralToken(DocumentationCommentXmlNames.CrefAttributeName, DocumentationCommentXmlNames.CrefAttributeName)), + XmlString( + Token(SyntaxKind.DoubleQuoteToken), + SyntaxTokenList.Create( + XmlTextLiteralToken(linkAddressString, linkAddressString)), + Token(SyntaxKind.DoubleQuoteToken))))) + End Function + + ''' + ''' Creates a threadsafty element within an xml documentation comment. + ''' + Public Shared Function XmlThreadSafetyElement() As XmlEmptyElementSyntax + Return XmlThreadSafetyElement(True, False) + End Function + + ''' + ''' Creates a threadsafty element within an xml documentation comment. + ''' + ''' Indicates whether static member of this class are safe for multi-threaded operations. + ''' Indicates whether members of instances of this type are safe for multi-threaded operations. + ''' + Public Shared Function XmlThreadSafetyElement([static] As Boolean, instance As Boolean) As XmlEmptyElementSyntax + Dim staticValueString = [static].ToString().ToLowerInvariant() + Dim instanceValueString = instance.ToString().ToLowerInvariant() + + Return XmlEmptyElement(XmlName(Nothing, XmlNameToken(DocumentationCommentXmlNames.ThreadSafetyElementName, SyntaxKind.XmlNameToken)).WithTrailingTrivia(ElasticSpace)).AddAttributes( + XmlAttribute( + XmlName(Nothing, XmlNameToken(DocumentationCommentXmlNames.StaticAttributeName, SyntaxKind.XmlNameToken)), + XmlString( + Token(SyntaxKind.DoubleQuoteToken), + SyntaxTokenList.Create(XmlTextLiteralToken(staticValueString, staticValueString)), + Token(SyntaxKind.DoubleQuoteToken))).WithTrailingTrivia(ElasticSpace), + XmlAttribute( + XmlName(Nothing, XmlNameToken(DocumentationCommentXmlNames.InstanceAttributeName, SyntaxKind.XmlNameToken)), + XmlString( + Token(SyntaxKind.DoubleQuoteToken), + SyntaxTokenList.Create(XmlTextLiteralToken(instanceValueString, instanceValueString)), + Token(SyntaxKind.DoubleQuoteToken)))) + End Function + + ''' + ''' Creates a syntax node for a name attribute in a xml element within a xml documentation comment. + ''' + ''' The value of the name attribute. + Public Shared Function XmlNameAttribute(parameterName As String) As XmlNameAttributeSyntax + Return XmlNameAttribute(XmlName(Nothing, XmlNameToken(DocumentationCommentXmlNames.NameAttributeName, SyntaxKind.XmlNameToken)), Token(SyntaxKind.DoubleQuoteToken), IdentifierName(parameterName), Token(SyntaxKind.DoubleQuoteToken)).WithLeadingTrivia(Whitespace(" ")) + End Function + + ''' + ''' Creates a syntax node for a priliminary element within a xml documentation comment. + ''' + Public Shared Function XmlPreliminaryElement() As XmlEmptyElementSyntax + Return XmlEmptyElement(DocumentationCommentXmlNames.PreliminaryElementName) + End Function + + ''' + ''' Creates a syntax node for a cref attribute within a xml documentation comment. + ''' + ''' The used for the xml cref attribute syntax. + Public Shared Function XmlCrefAttribute(cref As CrefReferenceSyntax) As XmlCrefAttributeSyntax + Return XmlCrefAttribute(cref, SyntaxKind.DoubleQuoteToken) + End Function + + ''' + ''' Creates a syntax node for a cref attribute within a xml documentation comment. + ''' + ''' The used for the xml cref attribute syntax. + ''' The kind of the quote for the referenced item in the cref attribute. + Public Shared Function XmlCrefAttribute(cref As CrefReferenceSyntax, quoteKind As SyntaxKind) As XmlCrefAttributeSyntax + cref = cref.ReplaceTokens(cref.DescendantTokens(), AddressOf XmlReplaceBracketTokens) + Return XmlCrefAttribute(XmlName(Nothing, XmlNameToken(DocumentationCommentXmlNames.CrefAttributeName, SyntaxKind.XmlNameToken)), Token(quoteKind), cref, Token(quoteKind)).WithLeadingTrivia(Whitespace(" ")) + End Function + + ''' + ''' Creates a remarks element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the remarks element. + Public Shared Function XmlRemarksElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlRemarksElement(List(content)) + End Function + + ''' + ''' Creates a remarks element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the remarks element. + Public Shared Function XmlRemarksElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlMultiLineElement(DocumentationCommentXmlNames.RemarksElementName, content) + End Function + + ''' + ''' Creates a returns element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the returns element. + Public Shared Function XmlReturnsElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlReturnsElement(List(content)) + End Function + + ''' + ''' Creates a returns element within an xml documentation comment. + ''' + ''' A list of xml node syntax that will be the content within the returns element. + Public Shared Function XmlReturnsElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlMultiLineElement(DocumentationCommentXmlNames.ReturnsElementName, content) + End Function + + ''' + ''' Creates the the syntax representation of an xml value element (e.g. for xml documentation comments). + ''' + ''' A list of xml syntax nodes that represents the content of the value element. + Public Shared Function XmlValueElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlValueElement(List(content)) + End Function + + ''' + ''' Creates the the syntax representation of an xml value element (e.g. for xml documentation comments). + ''' + ''' A list of xml syntax nodes that represents the content of the value element. + Public Shared Function XmlValueElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlMultiLineElement(DocumentationCommentXmlNames.ValueElementName, content) + End Function + + ''' + ''' Creates the syntax representation of an exception element within xml documentation comments. + ''' + ''' Syntax representation of the reference to the exception type. + ''' A list of syntax nodes that represents the content of the exception element. + Public Shared Function XmlExceptionElement(cref As CrefReferenceSyntax, ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlExceptionElement(cref, List(content)) + End Function + + ''' + ''' Creates the syntax representation of an exception element within xml documentation comments. + ''' + ''' Syntax representation of the reference to the exception type. + ''' A list of syntax nodes that represents the content of the exception element. + Public Shared Function XmlExceptionElement(cref As CrefReferenceSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Dim element As XmlElementSyntax = XmlElement(DocumentationCommentXmlNames.ExceptionElementName, content) + Return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))) + End Function + + ''' + ''' Creates the syntax representation of a permission element within xml documentation comments. + ''' + ''' Syntax representation of the reference to the permission type. + ''' A list of syntax nodes that represents the content of the permission element. + Public Shared Function XmlPermissionElement(cref As CrefReferenceSyntax, ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlPermissionElement(cref, List(content)) + End Function + + ''' + ''' Creates the syntax representation of a permission element within xml documentation comments. + ''' + ''' Syntax representation of the reference to the permission type. + ''' A list of syntax nodes that represents the content of the permission element. + Public Shared Function XmlPermissionElement(cref As CrefReferenceSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Dim element As XmlElementSyntax = XmlElement(DocumentationCommentXmlNames.PermissionElementName, content) + Return element.WithStartTag(element.StartTag.AddAttributes(XmlCrefAttribute(cref))) + End Function + + ''' + ''' Creates the syntax representation of an example element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the example element. + Public Shared Function XmlExampleElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlExampleElement(List(content)) + End Function + + ''' + ''' Creates the syntax representation of an example element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the example element. + Public Shared Function XmlExampleElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Dim element As XmlElementSyntax = XmlElement(DocumentationCommentXmlNames.ExampleElementName, content) + Return element.WithStartTag(element.StartTag) + End Function + + ''' + ''' Creates the syntax representation of a para element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the para element. + Public Shared Function XmlParaElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlParaElement(List(content)) + End Function + + ''' + ''' Creates the syntax representation of a para element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the para element. + Public Shared Function XmlParaElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlElement(DocumentationCommentXmlNames.ParaElementName, content) + End Function + + ''' + ''' Creates the syntax representation of a param element within xml documentation comments (e.g. for + ''' documentation of method parameters). + ''' + ''' The name of the parameter. + ''' A list of syntax nodes that represents the content of the param element (e.g. + ''' the description and meaning of the parameter). + Public Shared Function XmlParamElement(parameterName As String, ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlParamElement(parameterName, List(content)) + End Function + + ''' + ''' Creates the syntax representation of a param element within xml documentation comments (e.g. for + ''' documentation of method parameters). + ''' + ''' The name of the parameter. + ''' A list of syntax nodes that represents the content of the param element (e.g. + ''' the description and meaning of the parameter). + Public Shared Function XmlParamElement(parameterName As String, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Dim element As XmlElementSyntax = XmlElement(DocumentationCommentXmlNames.ParameterElementName, content) + Return element.WithStartTag(element.StartTag.AddAttributes(XmlNameAttribute(parameterName))) + End Function + + ''' + ''' Creates the syntax representation of a paramref element within xml documentation comments (e.g. for + ''' referencing particular parameters of a method). + ''' + ''' The name of the referenced parameter. + Public Shared Function XmlParamRefElement(parameterName As String) As XmlEmptyElementSyntax + Return XmlEmptyElement(DocumentationCommentXmlNames.ParameterReferenceElementName).AddAttributes(XmlNameAttribute(parameterName)) + End Function + + ''' + ''' Creates the syntax representation of a see element within xml documentation comments, + ''' that points to the 'null' language keyword. + ''' + Public Shared Function XmlNullKeywordElement() As XmlEmptyElementSyntax + Return XmlKeywordElement("null") + End Function + + ''' + ''' Creates the syntax representation of a see element within xml documentation comments, + ''' that points to a language keyword. + ''' + ''' The language keyword to which the see element points to. + Private Shared Function XmlKeywordElement(keyword As String) As XmlEmptyElementSyntax + Dim attribute As XmlAttributeSyntax = + XmlAttribute( + XmlName( + Nothing, + XmlTextLiteralToken(DocumentationCommentXmlNames.KeywordElementName, DocumentationCommentXmlNames.KeywordElementName)), + XmlString( + Token(SyntaxKind.DoubleQuoteToken), + SyntaxTokenList.Create(XmlTextLiteralToken(keyword, keyword)), + Token(SyntaxKind.DoubleQuoteToken))) + + Return XmlEmptyElement(DocumentationCommentXmlNames.SeeElementName).AddAttributes(attribute) + End Function + + ''' + ''' Creates the syntax representation of a placeholder element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the placeholder element. + Public Shared Function XmlPlaceholderElement(ParamArray content As XmlNodeSyntax()) As XmlElementSyntax + Return XmlPlaceholderElement(List(content)) + End Function + + ''' + ''' Creates the syntax representation of a placeholder element within xml documentation comments. + ''' + ''' A list of syntax nodes that represents the content of the placeholder element. + Public Shared Function XmlPlaceholderElement(content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlElement(DocumentationCommentXmlNames.PlaceholderElementName, content) + End Function + + ''' + ''' Creates the syntax representation of a named empty xml element within xml documentation comments. + ''' + ''' The name of the empty xml element. + Public Shared Function XmlEmptyElement(localName As String) As XmlEmptyElementSyntax + Return XmlEmptyElement(XmlName(Nothing, XmlNameToken(localName, SyntaxKind.XmlNameToken))) + End Function + + ''' + ''' Creates the syntax representation of a named xml element within xml documentation comments. + ''' + ''' The name of the empty xml element. + ''' A list of syntax nodes that represents the content of the xml element. + Public Shared Function XmlElement(localName As String, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlElement(XmlName(Nothing, XmlNameToken(localName, SyntaxKind.XmlNameToken)), content) + End Function + + ''' + ''' Creates the syntax representation of a named xml element within xml documentation comments. + ''' + ''' The name of the empty xml element. + ''' A list of syntax nodes that represents the content of the xml element. + Public Shared Function XmlElement(name As XmlNameSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlElement(XmlElementStartTag(name), content, XmlElementEndTag(name)) + End Function + + ''' + ''' Creates the syntax representation of an xml element that spans multiple text lines. + ''' + ''' The name of the xml element. + ''' A list of syntax nodes that represents the content of the xml multi line element. + Public Shared Function XmlMultiLineElement(localName As String, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlMultiLineElement(XmlName(Nothing, XmlNameToken(localName, SyntaxKind.XmlNameToken)), content) + End Function + + ''' + ''' Creates the syntax representation of an xml element that spans multiple text lines. + ''' + ''' The name of the xml element. + ''' A list of syntax nodes that represents the content of the xml multi line element. + Public Shared Function XmlMultiLineElement(name As XmlNameSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax + Return XmlElement(XmlElementStartTag(name), content.Insert(0, XmlNewLine()).Add(XmlNewLine()), XmlElementEndTag(name)) + End Function + + ''' + ''' Creates the syntax representation of an xml text that contains a newline token with a documentation comment + ''' exterior trivia at the end (continued documentation comment). + ''' + Public Shared Function XmlNewLine() As XmlTextSyntax + Return XmlText(XmlTextNewLine()) + End Function + + ''' + ''' Creates the syntax representation of an xml newline token with a documentation comment exterior trivia at + ''' the end (continued documentation comment). + ''' + Public Shared Function XmlTextNewLine() As SyntaxToken + Return XmlTextNewLine(True) + End Function + + ''' + ''' Creates the syntax representation of an xml newline token for xml documentation comments. + ''' + ''' + ''' If set to true, a documentation comment exterior token will be added to the trailing trivia + ''' of the new token. + Public Shared Function XmlTextNewLine(continueXmlDocumentationComment As Boolean) As SyntaxToken + Dim token As SyntaxToken = XmlTextNewLine( + TriviaList(), + Environment.NewLine, + Environment.NewLine, + TriviaList()) + + If continueXmlDocumentationComment Then + token = token.WithTrailingTrivia(DocumentationCommentExteriorTrivia("''' ")) + End If + + Return token + End Function + + ''' + ''' Creates a token with kind XmlTextLiteralNewLineToken. + ''' + ''' A list of trivia immediately preceding the token. + ''' The raw text of the literal. + ''' The xml text new line value. + ''' A list of trivia immediately following the token. + Public Shared Function XmlTextNewLine(leading As SyntaxTriviaList, text As String, value As String, trailing As SyntaxTriviaList) As SyntaxToken + Return New SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.DocumentationCommentLineBreakToken(text, value, DirectCast(leading.Node, InternalSyntax.VisualBasicSyntaxNode), DirectCast(trailing.Node, InternalSyntax.VisualBasicSyntaxNode))) + End Function + + ''' + ''' Generates the syntax representation of a xml text node (e.g. for xml documentation comments). + ''' + ''' The string literal used as the text of the xml text node. + Public Shared Function XmlText(value As String) As XmlTextSyntax + Return XmlText(XmlTextLiteral(value)) + End Function + + ''' + ''' Generates the syntax representation of a xml text node (e.g. for xml documentation comments). + ''' + ''' A list of text tokens used as the text of the xml text node. + Public Shared Function XmlText(ParamArray textTokens As SyntaxToken()) As XmlTextSyntax + Return XmlText(TokenList(textTokens)) + End Function + + ''' + ''' Generates the syntax representation of an xml text literal. + ''' + ''' The text used within the xml text literal. + Public Shared Function XmlTextLiteral(value As String) As SyntaxToken + ' TODO: [RobinSedlaczek] It is no compiler hot path here I think. But the contribution guide + ' states to avoid LINQ (https://github.com/dotnet/roslyn/wiki/Contributing-Code). With + ' XText we have a reference to System.Xml.Linq. Isn't this rule valid here? + Dim encoded As String = New XText(value).ToString() + + Return XmlTextLiteral(encoded, value) + End Function + + ''' + ''' Generates the syntax representation of an xml text literal. + ''' + ''' The raw text of the literal. + ''' The text used within the xml text literal. + Public Shared Function XmlTextLiteral(text As String, value As String) As SyntaxToken + Return New SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextLiteralToken(text, value, DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode), DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode))) + End Function + + ''' + ''' Helper method that replaces less-than and greater-than characters with brackets. + ''' + ''' The original token that is to be replaced. + ''' The new rewritten token. + ''' Returns the new rewritten token with replaced characters. + Private Shared Function XmlReplaceBracketTokens(originalToken As SyntaxToken, rewrittenToken As SyntaxToken) As SyntaxToken + If rewrittenToken.IsKind(SyntaxKind.LessThanToken) AndAlso String.Equals("<", rewrittenToken.Text, StringComparison.Ordinal) Then + Return Token(rewrittenToken.LeadingTrivia, SyntaxKind.LessThanToken, rewrittenToken.TrailingTrivia, rewrittenToken.ValueText) + End If + + If rewrittenToken.IsKind(SyntaxKind.GreaterThanToken) AndAlso String.Equals(">", rewrittenToken.Text, StringComparison.Ordinal) Then + Return Token(rewrittenToken.LeadingTrivia, SyntaxKind.GreaterThanToken, rewrittenToken.TrailingTrivia, rewrittenToken.ValueText) + End If + + Return rewrittenToken + End Function + ''' ''' Determines if two trees are the same, disregarding trivia differences. ''' diff --git a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb index fdcf10e25febb..2e74b2465a538 100644 --- a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb +++ b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb @@ -549,4 +549,223 @@ End Module ) End Sub + + + Public Sub TestDocumentationComment() + Dim expected = + "''' " & vbCr & vbLf & + "''' This class provides extension methods for the class." & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods for the "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText(" class.")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlThreadSafetyElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlPreliminaryElement()) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlSummaryElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' This class provides extension methods." & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlSeeElementAndXmlSeeAlsoElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' This class provides extension methods for the class and the class." & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This class provides extension methods for the "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText(" class and the "), + SyntaxFactory.XmlSeeAlsoElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("TypeName2"))), + SyntaxFactory.XmlText(" class."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlNewLineElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' This is a summary." & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlText("This is a summary.")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlRemarksElement()) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlParamAndParamRefElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlParamRefElement("b")), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlParamElement("a"), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlParamElement("b")) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlReturnsElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' Returns a value." & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlReturnsElement( + SyntaxFactory.XmlText("Returns a value."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlRemarksElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' Same as in class ." & vbCr & vbLf & + "''' " & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlRemarksElement( + SyntaxFactory.XmlText("Same as in class "), + SyntaxFactory.XmlSeeElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("TypeName"))), + SyntaxFactory.XmlText("."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlExceptionElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' This exception will be thrown if the object is in an invalid state when calling this method." & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlExceptionElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("InvalidOperationException")), + SyntaxFactory.XmlText("This exception will be thrown if the object is in an invalid state when calling this method."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + + + + Public Sub TestXmlPermissionElement() + Dim expected = + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' " & vbCr & vbLf & + "''' Needs MyPermission to execute." & vbCr & vbLf + + Dim documentationComment As DocumentationCommentTriviaSyntax = + SyntaxFactory.DocumentationComment( + SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlPermissionElement( + SyntaxFactory.CrefReference( + SyntaxFactory.ParseTypeName("MyPermission")), + SyntaxFactory.XmlText("Needs MyPermission to execute."))) + + Dim actual = documentationComment.ToFullString() + + Assert.Equal(Of String)(expected, actual) + End Sub + End Class From 95ea4dbcc6284f1c21ccedbed9b673ccedf34aa0 Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Wed, 9 Dec 2015 08:22:50 +0100 Subject: [PATCH 08/13] Use Environment.Newline rather then vbCrLf in unit tests to get platform independent strings that can be compared in assertions. --- .../Test/Syntax/Parser/XmlDocComments.vb | 88 +++++++++---------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb index 2e74b2465a538..25eb57c9145a1 100644 --- a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb +++ b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb @@ -553,11 +553,11 @@ End Module Public Sub TestDocumentationComment() Dim expected = - "''' " & vbCr & vbLf & - "''' This class provides extension methods for the class." & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' This class provides extension methods for the class." & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -581,9 +581,9 @@ End Module Public Sub TestXmlSummaryElement() Dim expected = - "''' " & vbCr & vbLf & - "''' This class provides extension methods." & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' This class provides extension methods." & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -599,9 +599,9 @@ End Module Public Sub TestXmlSeeElementAndXmlSeeAlsoElement() Dim expected = - "''' " & vbCr & vbLf & - "''' This class provides extension methods for the class and the class." & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' This class provides extension methods for the class and the class." & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -625,14 +625,14 @@ End Module Public Sub TestXmlNewLineElement() Dim expected = - "''' " & vbCr & vbLf & - "''' This is a summary." & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' This is a summary." & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -652,11 +652,11 @@ End Module Public Sub TestXmlParamAndParamRefElement() Dim expected = - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -676,12 +676,12 @@ End Module Public Sub TestXmlReturnsElement() Dim expected = - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' Returns a value." & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' Returns a value." & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -699,12 +699,12 @@ End Module Public Sub TestXmlRemarksElement() Dim expected = - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' Same as in class ." & vbCr & vbLf & - "''' " & vbCr & vbLf + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' Same as in class ." & Environment.NewLine & + "''' " & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -726,10 +726,10 @@ End Module Public Sub TestXmlExceptionElement() Dim expected = - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' This exception will be thrown if the object is in an invalid state when calling this method." & vbCr & vbLf + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' This exception will be thrown if the object is in an invalid state when calling this method." & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -749,10 +749,10 @@ End Module Public Sub TestXmlPermissionElement() Dim expected = - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' " & vbCr & vbLf & - "''' Needs MyPermission to execute." & vbCr & vbLf + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' " & Environment.NewLine & + "''' Needs MyPermission to execute." & Environment.NewLine Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( From 5717e01e1d13a92ec4e3398023c74517a39601a7 Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Thu, 10 Dec 2015 21:52:34 +0100 Subject: [PATCH 09/13] Make syntax factory methods for documenttation comments more consistent between C# and Visual Basic. Fix problems with elastic trivias. --- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 38 ++++++++++++------- .../Portable/PublicAPI.Unshipped.txt | 3 +- .../Portable/Syntax/SyntaxFactory.vb | 37 ++++++++++++++++-- 3 files changed, 59 insertions(+), 19 deletions(-) diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index f0b0d827d1a0d..5aaf81c0c21a3 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -641,18 +641,6 @@ public static SyntaxToken XmlTextLiteral(SyntaxTriviaList leading, string text, return new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextLiteral((InternalSyntax.CSharpSyntaxNode)leading.Node, text, value, (InternalSyntax.CSharpSyntaxNode)trailing.Node)); } - /// - /// Creates a token with kind XmlTextLiteralNewLineToken. - /// - /// A list of trivia immediately preceding the token. - /// The raw text of the literal. - /// The xml text new line value. - /// A list of trivia immediately following the token. - public static SyntaxToken XmlTextNewLine(SyntaxTriviaList leading, string text, string value, SyntaxTriviaList trailing) - { - return new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextNewLine((InternalSyntax.CSharpSyntaxNode)leading.Node, text, value, (InternalSyntax.CSharpSyntaxNode)trailing.Node)); - } - /// /// Creates a token with kind XmlEntityLiteralToken. /// @@ -1139,6 +1127,23 @@ public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) return token; } + /// + /// Creates a token with kind XmlTextLiteralNewLineToken. + /// + /// A list of trivia immediately preceding the token. + /// The raw text of the literal. + /// The xml text new line value. + /// A list of trivia immediately following the token. + public static SyntaxToken XmlTextNewLine(SyntaxTriviaList leading, string text, string value, SyntaxTriviaList trailing) + { + return new SyntaxToken( + InternalSyntax.SyntaxFactory.XmlTextNewLine( + (InternalSyntax.CSharpSyntaxNode)leading.Node, + text, + value, + (InternalSyntax.CSharpSyntaxNode)trailing.Node)); + } + /// /// Creates the syntax representation of an xml newline token for xml documentation comments. /// @@ -1149,10 +1154,15 @@ public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) public static SyntaxToken XmlTextNewLine(string text, bool continueXmlDocumentationComment) { var value = Environment.NewLine; - var token = new SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.XmlTextNewLine((InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode, text, value, (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode)); + var token = new SyntaxToken( + InternalSyntax.SyntaxFactory.XmlTextNewLine( + (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode, + text, + value, + (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode)); if (continueXmlDocumentationComment) - token = token.WithTrailingTrivia(DocumentationCommentExterior("/// ")); + token = token.WithTrailingTrivia(token.TrailingTrivia.Add(DocumentationCommentExterior("/// "))); return token; } diff --git a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt index 487544c6f016d..2bc7054e8df6b 100644 --- a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt @@ -56,7 +56,8 @@ Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(text As S Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(value As String) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(continueXmlDocumentationComment As Boolean) -> Microsoft.CodeAnalysis.SyntaxToken -Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(leading As Microsoft.CodeAnalysis.SyntaxTriviaList, text As String, value As String, trailing As Microsoft.CodeAnalysis.SyntaxTriviaList) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(text As String, continueXmlDocumentationComment As Boolean) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(text As String, value As String, leading As Microsoft.CodeAnalysis.SyntaxTriviaList, trailing As Microsoft.CodeAnalysis.SyntaxTriviaList) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlThreadSafetyElement(static As Boolean, instance As Boolean) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlValueElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax diff --git a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb index 832a92823de20..c4e35b9c0a542 100644 --- a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb +++ b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb @@ -839,9 +839,9 @@ Namespace Microsoft.CodeAnalysis.VisualBasic ''' of the new token. Public Shared Function XmlTextNewLine(continueXmlDocumentationComment As Boolean) As SyntaxToken Dim token As SyntaxToken = XmlTextNewLine( - TriviaList(), Environment.NewLine, Environment.NewLine, + TriviaList(), TriviaList()) If continueXmlDocumentationComment Then @@ -851,15 +851,44 @@ Namespace Microsoft.CodeAnalysis.VisualBasic Return token End Function + ''' ''' Creates a token with kind XmlTextLiteralNewLineToken. ''' - ''' A list of trivia immediately preceding the token. ''' The raw text of the literal. ''' The xml text new line value. + ''' A list of trivia immediately preceding the token. ''' A list of trivia immediately following the token. - Public Shared Function XmlTextNewLine(leading As SyntaxTriviaList, text As String, value As String, trailing As SyntaxTriviaList) As SyntaxToken - Return New SyntaxToken(Syntax.InternalSyntax.SyntaxFactory.DocumentationCommentLineBreakToken(text, value, DirectCast(leading.Node, InternalSyntax.VisualBasicSyntaxNode), DirectCast(trailing.Node, InternalSyntax.VisualBasicSyntaxNode))) + Public Shared Function XmlTextNewLine(text As String, value As String, leading As SyntaxTriviaList, trailing As SyntaxTriviaList) As SyntaxToken + Return New SyntaxToken( + InternalSyntax.SyntaxFactory.DocumentationCommentLineBreakToken( + text, + value, + DirectCast(leading.Node, InternalSyntax.VisualBasicSyntaxNode), + DirectCast(trailing.Node, InternalSyntax.VisualBasicSyntaxNode))) + End Function + + ''' + ''' Creates the syntax representation of an xml newline token for xml documentation comments. + ''' + ''' The raw text within the new line. + ''' + ''' If set to true, a documentation comment exterior token will be added to the trailing trivia + ''' of the new token. + Public Shared Function XmlTextNewLine(text As String, continueXmlDocumentationComment As Boolean) As SyntaxToken + Dim value = Environment.NewLine + Dim token = New SyntaxToken( + InternalSyntax.SyntaxFactory.DocumentationCommentLineBreakToken( + text, + value, + DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode), + DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode))) + + If continueXmlDocumentationComment Then + token = token.WithTrailingTrivia(token.TrailingTrivia.Add(DocumentationCommentExteriorTrivia("''' "))) + End If + + Return token End Function ''' From b69629cb1a1183aae2b4850f18359f7fbff8736c Mon Sep 17 00:00:00 2001 From: "robin:sedlaczek" Date: Tue, 5 Jan 2016 23:30:38 +0100 Subject: [PATCH 10/13] Handle new line problem and remove usage of Environment.NewLine. --- .../CSharp/Portable/PublicAPI.Unshipped.txt | 5 +- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 43 ++----- .../LexicalAndXml/XmlDocCommentTests.cs | 118 +++++++++--------- .../Portable/PublicAPI.Unshipped.txt | 5 +- .../Portable/Syntax/SyntaxFactory.vb | 37 ++---- .../Test/Syntax/Parser/XmlDocComments.vb | 112 ++++++++--------- 6 files changed, 137 insertions(+), 183 deletions(-) diff --git a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt index d692523153c22..deca53f20cd8d 100644 --- a/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt @@ -69,7 +69,7 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlExceptionElement(Microsoft static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameSyntax name, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(string localName, Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNameAttribute(string parameterName) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlNameAttributeSyntax -static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNewLine() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextSyntax +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNewLine(string text) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlNullKeywordElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParaElement(Microsoft.CodeAnalysis.SyntaxList content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlParaElement(params Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax[] content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax @@ -98,8 +98,7 @@ static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextAttribute(string name, string value) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlTextAttributeSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string text, string value) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string value) -> Microsoft.CodeAnalysis.SyntaxToken -static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken -static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(bool continueXmlDocumentationComment) -> Microsoft.CodeAnalysis.SyntaxToken +static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(string text) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextNewLine(string text, bool continueXmlDocumentationComment) -> Microsoft.CodeAnalysis.SyntaxToken static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlThreadSafetyElement(bool static, bool instance) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlEmptyElementSyntax diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 5aaf81c0c21a3..71aca38cebadc 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -664,7 +664,7 @@ public static DocumentationCommentTriviaSyntax DocumentationComment(params XmlNo { return DocumentationCommentTrivia(SyntaxKind.SingleLineDocumentationCommentTrivia, List(content)) .WithLeadingTrivia(DocumentationCommentExterior("/// ")) - .WithTrailingTrivia(EndOfLine(Environment.NewLine)); + .WithTrailingTrivia(EndOfLine("")); } /// @@ -1058,11 +1058,7 @@ public static XmlTextAttributeSyntax XmlTextAttribute(string name, SyntaxKind qu /// A list of tokens used for the value of the xml text attribute. public static XmlTextAttributeSyntax XmlTextAttribute(XmlNameSyntax name, SyntaxKind quoteKind, SyntaxTokenList textTokens) { - return XmlTextAttribute( - name, - Token(quoteKind), - textTokens, - Token(quoteKind)) + return XmlTextAttribute(name, Token(quoteKind), textTokens, Token(quoteKind)) .WithLeadingTrivia(Whitespace(" ")); } @@ -1085,7 +1081,7 @@ public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxLis { return XmlElement( XmlElementStartTag(name), - content.Insert(0, XmlNewLine()).Add(XmlNewLine()), + content.Insert(0, XmlNewLine("\r\n")).Add(XmlNewLine("\r\n")), XmlElementEndTag(name)); } @@ -1093,38 +1089,20 @@ public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxLis /// Creates the syntax representation of an xml text that contains a newline token with a documentation comment /// exterior trivia at the end (continued documentation comment). /// - public static XmlTextSyntax XmlNewLine() + /// The raw text within the new line. + public static XmlTextSyntax XmlNewLine(string text) { - return XmlText(XmlTextNewLine()); + return XmlText(XmlTextNewLine(text)); } /// /// Creates the syntax representation of an xml newline token with a documentation comment exterior trivia at /// the end (continued documentation comment). /// - public static SyntaxToken XmlTextNewLine() - { - return XmlTextNewLine(true); - } - - /// - /// Creates the syntax representation of an xml newline token for xml documentation comments. - /// - /// - /// If set to true, a documentation comment exterior token will be added to the trailing trivia - /// of the new token. - public static SyntaxToken XmlTextNewLine(bool continueXmlDocumentationComment) + /// The raw text within the new line. + public static SyntaxToken XmlTextNewLine(string text) { - SyntaxToken token = XmlTextNewLine( - TriviaList(), - Environment.NewLine, - Environment.NewLine, - TriviaList()); - - if (continueXmlDocumentationComment) - token = token.WithTrailingTrivia(DocumentationCommentExterior("/// ")); - - return token; + return XmlTextNewLine(text, true); } /// @@ -1153,12 +1131,11 @@ public static SyntaxToken XmlTextNewLine(SyntaxTriviaList leading, string text, /// of the new token. public static SyntaxToken XmlTextNewLine(string text, bool continueXmlDocumentationComment) { - var value = Environment.NewLine; var token = new SyntaxToken( InternalSyntax.SyntaxFactory.XmlTextNewLine( (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode, text, - value, + text, (InternalSyntax.CSharpSyntaxNode)ElasticMarker.UnderlyingNode)); if (continueXmlDocumentationComment) diff --git a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs index b092eb39b0a54..8cdf24f878efb 100644 --- a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs @@ -2865,12 +2865,12 @@ public class Program [Trait("Feature", "Xml Documentation Comments")] public void TestDocumentationComment() { - var expected = @"/// -/// This class provides extension methods for the class. -/// -/// -/// -"; + var expected = + "/// \r\n" + + "/// This class provides extension methods for the class.\r\n" + + "/// \r\n" + + "/// \r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( @@ -2878,9 +2878,9 @@ public void TestDocumentationComment() SyntaxFactory.XmlSeeElement( SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), SyntaxFactory.XmlText(" class.")), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlThreadSafetyElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPreliminaryElement()); var actual = documentationComment.ToFullString(); @@ -2894,8 +2894,7 @@ public void TestXmlSummaryElement() { var expected = @"/// /// This class provides extension methods. -/// -"; +/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( @@ -2912,8 +2911,7 @@ public void TestXmlSeeElementAndXmlSeeAlsoElement() { var expected = @"/// /// This class provides extension methods for the class and the class. -/// -"; +/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( @@ -2934,22 +2932,22 @@ public void TestXmlSeeElementAndXmlSeeAlsoElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlNewLineElement() { - var expected = @"/// -/// This is a summary. -/// -/// -/// -/// -/// -/// -"; + var expected = + "/// \r\n" + + "/// This is a summary.\r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( SyntaxFactory.XmlText("This is a summary.")), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement()); var actual = documentationComment.ToFullString(); @@ -2961,19 +2959,19 @@ public void TestXmlNewLineElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlParamAndParamRefElement() { - var expected = @"/// -/// -/// -/// -/// -"; + var expected = + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( SyntaxFactory.XmlParamRefElement("b")), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("a"), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("b")); var actual = documentationComment.ToFullString(); @@ -2985,17 +2983,17 @@ public void TestXmlParamAndParamRefElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlReturnsElement() { - var expected = @"/// -/// -/// -/// -/// Returns a value. -/// -"; + var expected = + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// Returns a value.\r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlReturnsElement( SyntaxFactory.XmlText("Returns a value."))); @@ -3008,17 +3006,17 @@ public void TestXmlReturnsElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlRemarksElement() { - var expected = @"/// -/// -/// -/// -/// Same as in class . -/// -"; + var expected = + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// Same as in class .\r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement( SyntaxFactory.XmlText("Same as in class "), SyntaxFactory.XmlSeeElement(SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), @@ -3033,15 +3031,15 @@ public void TestXmlRemarksElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlExceptionElement() { - var expected = @"/// -/// -/// -/// This exception will be thrown if the object is in an invalid state when calling this method. -"; + var expected = + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// This exception will be thrown if the object is in an invalid state when calling this method."; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlExceptionElement( SyntaxFactory.TypeCref( SyntaxFactory.ParseTypeName("InvalidOperationException")), @@ -3056,15 +3054,15 @@ public void TestXmlExceptionElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlPermissionElement() { - var expected = @"/// -/// -/// -/// Needs MyPermission to execute. -"; + var expected = + "/// \r\n" + + "/// \r\n" + + "/// \r\n" + + "/// Needs MyPermission to execute."; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPermissionElement( SyntaxFactory.TypeCref( SyntaxFactory.ParseTypeName("MyPermission")), diff --git a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt index 2bc7054e8df6b..36a0e6b51d996 100644 --- a/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt +++ b/src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt @@ -29,7 +29,7 @@ Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlExceptionElement(cref Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlMultiLineElement(localName As String, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlMultiLineElement(name As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNameSyntax, content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNameAttribute(parameterName As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNameAttributeSyntax -Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNewLine() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNewLine(text As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlNullKeywordElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParaElement(ParamArray content As Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax()) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlParaElement(content As Microsoft.CodeAnalysis.SyntaxList(Of Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlNodeSyntax)) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlElementSyntax @@ -54,8 +54,7 @@ Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlText(ParamArray textT Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlText(value As String) -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlTextSyntax Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(text As String, value As String) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextLiteral(value As String) -> Microsoft.CodeAnalysis.SyntaxToken -Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine() -> Microsoft.CodeAnalysis.SyntaxToken -Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(continueXmlDocumentationComment As Boolean) -> Microsoft.CodeAnalysis.SyntaxToken +Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(text As String) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(text As String, continueXmlDocumentationComment As Boolean) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlTextNewLine(text As String, value As String, leading As Microsoft.CodeAnalysis.SyntaxTriviaList, trailing As Microsoft.CodeAnalysis.SyntaxTriviaList) -> Microsoft.CodeAnalysis.SyntaxToken Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.XmlThreadSafetyElement() -> Microsoft.CodeAnalysis.VisualBasic.Syntax.XmlEmptyElementSyntax diff --git a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb index c4e35b9c0a542..1e02c46ddb1b3 100644 --- a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb +++ b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb @@ -458,7 +458,7 @@ Namespace Microsoft.CodeAnalysis.VisualBasic ''' (e.g. a summary element, a returns element, exception element and so on). ''' Public Shared Function DocumentationComment(ParamArray content As XmlNodeSyntax()) As DocumentationCommentTriviaSyntax - Return DocumentationCommentTrivia(List(content)).WithLeadingTrivia(DocumentationCommentExteriorTrivia("''' ")).WithTrailingTrivia(EndOfLine(Environment.NewLine)) + Return DocumentationCommentTrivia(List(content)).WithLeadingTrivia(DocumentationCommentExteriorTrivia("''' ")).WithTrailingTrivia(EndOfLine("")) End Function ''' @@ -812,43 +812,25 @@ Namespace Microsoft.CodeAnalysis.VisualBasic ''' The name of the xml element. ''' A list of syntax nodes that represents the content of the xml multi line element. Public Shared Function XmlMultiLineElement(name As XmlNameSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax - Return XmlElement(XmlElementStartTag(name), content.Insert(0, XmlNewLine()).Add(XmlNewLine()), XmlElementEndTag(name)) + Return XmlElement(XmlElementStartTag(name), content.Insert(0, XmlNewLine("\r\n")).Add(XmlNewLine("\r\n")), XmlElementEndTag(name)) End Function ''' ''' Creates the syntax representation of an xml text that contains a newline token with a documentation comment ''' exterior trivia at the end (continued documentation comment). ''' - Public Shared Function XmlNewLine() As XmlTextSyntax - Return XmlText(XmlTextNewLine()) + ''' The raw text within the new line. + Public Shared Function XmlNewLine(text As String) As XmlTextSyntax + Return XmlText(XmlTextNewLine(text)) End Function ''' ''' Creates the syntax representation of an xml newline token with a documentation comment exterior trivia at ''' the end (continued documentation comment). ''' - Public Shared Function XmlTextNewLine() As SyntaxToken - Return XmlTextNewLine(True) - End Function - - ''' - ''' Creates the syntax representation of an xml newline token for xml documentation comments. - ''' - ''' - ''' If set to true, a documentation comment exterior token will be added to the trailing trivia - ''' of the new token. - Public Shared Function XmlTextNewLine(continueXmlDocumentationComment As Boolean) As SyntaxToken - Dim token As SyntaxToken = XmlTextNewLine( - Environment.NewLine, - Environment.NewLine, - TriviaList(), - TriviaList()) - - If continueXmlDocumentationComment Then - token = token.WithTrailingTrivia(DocumentationCommentExteriorTrivia("''' ")) - End If - - Return token + ''' The raw text within the new line. + Public Shared Function XmlTextNewLine(text As String) As SyntaxToken + Return XmlTextNewLine(text, True) End Function @@ -876,11 +858,10 @@ Namespace Microsoft.CodeAnalysis.VisualBasic ''' If set to true, a documentation comment exterior token will be added to the trailing trivia ''' of the new token. Public Shared Function XmlTextNewLine(text As String, continueXmlDocumentationComment As Boolean) As SyntaxToken - Dim value = Environment.NewLine Dim token = New SyntaxToken( InternalSyntax.SyntaxFactory.DocumentationCommentLineBreakToken( text, - value, + text, DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode), DirectCast(ElasticMarker.UnderlyingNode, InternalSyntax.VisualBasicSyntaxNode))) diff --git a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb index 25eb57c9145a1..a87e4ab35df47 100644 --- a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb +++ b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb @@ -553,11 +553,11 @@ End Module Public Sub TestDocumentationComment() Dim expected = - "''' " & Environment.NewLine & - "''' This class provides extension methods for the class." & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' This class provides extension methods for the class.\r\n" & + "''' \r\n" & + "''' \r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -567,9 +567,9 @@ End Module SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("TypeName"))), SyntaxFactory.XmlText(" class.")), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlThreadSafetyElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPreliminaryElement()) Dim actual = documentationComment.ToFullString() @@ -581,14 +581,14 @@ End Module Public Sub TestXmlSummaryElement() Dim expected = - "''' " & Environment.NewLine & - "''' This class provides extension methods." & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' This class provides extension methods.\r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This class provides extension methods."))) + SyntaxFactory.XmlText("This class provides extension methods."))) Dim actual = documentationComment.ToFullString() @@ -599,9 +599,9 @@ End Module Public Sub TestXmlSeeElementAndXmlSeeAlsoElement() Dim expected = - "''' " & Environment.NewLine & - "''' This class provides extension methods for the class and the class." & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' This class provides extension methods for the class and the class.\r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( @@ -625,22 +625,22 @@ End Module Public Sub TestXmlNewLineElement() Dim expected = - "''' " & Environment.NewLine & - "''' This is a summary." & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' This is a summary.\r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( SyntaxFactory.XmlText("This is a summary.")), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.XmlNewLine(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement()) Dim actual = documentationComment.ToFullString() @@ -652,19 +652,19 @@ End Module Public Sub TestXmlParamAndParamRefElement() Dim expected = - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( SyntaxFactory.XmlParamRefElement("b")), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("a"), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("b")) Dim actual = documentationComment.ToFullString() @@ -676,17 +676,17 @@ End Module Public Sub TestXmlReturnsElement() Dim expected = - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' Returns a value." & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' Returns a value.\r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlReturnsElement( SyntaxFactory.XmlText("Returns a value."))) @@ -699,17 +699,17 @@ End Module Public Sub TestXmlRemarksElement() Dim expected = - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' Same as in class ." & Environment.NewLine & - "''' " & Environment.NewLine + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' Same as in class .\r\n" & + "''' " Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement( SyntaxFactory.XmlText("Same as in class "), SyntaxFactory.XmlSeeElement( @@ -726,15 +726,15 @@ End Module Public Sub TestXmlExceptionElement() Dim expected = - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' This exception will be thrown if the object is in an invalid state when calling this method." & Environment.NewLine + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' This exception will be thrown if the object is in an invalid state when calling this method." Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlExceptionElement( SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("InvalidOperationException")), @@ -749,15 +749,15 @@ End Module Public Sub TestXmlPermissionElement() Dim expected = - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' " & Environment.NewLine & - "''' Needs MyPermission to execute." & Environment.NewLine + "''' \r\n" & + "''' \r\n" & + "''' \r\n" & + "''' Needs MyPermission to execute." Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement(), - SyntaxFactory.XmlNewLine(), + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPermissionElement( SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("MyPermission")), From 8b74f423a4726ad891ba6e53cd5bf4dd89eb22e4 Mon Sep 17 00:00:00 2001 From: robinsedlaczek Date: Wed, 6 Jan 2016 13:12:36 +0100 Subject: [PATCH 11/13] Provide new lines via content parameter in unit tests. --- .../CSharp/Portable/Syntax/SyntaxFactory.cs | 2 +- .../LexicalAndXml/XmlDocCommentTests.cs | 50 ++++++++++++++----- .../Portable/Syntax/SyntaxFactory.vb | 2 +- .../Test/Syntax/Parser/XmlDocComments.vb | 48 +++++++++++++----- 4 files changed, 75 insertions(+), 27 deletions(-) diff --git a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs index 71aca38cebadc..bd0f68d67519a 100644 --- a/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs +++ b/src/Compilers/CSharp/Portable/Syntax/SyntaxFactory.cs @@ -1081,7 +1081,7 @@ public static XmlElementSyntax XmlMultiLineElement(XmlNameSyntax name, SyntaxLis { return XmlElement( XmlElementStartTag(name), - content.Insert(0, XmlNewLine("\r\n")).Add(XmlNewLine("\r\n")), + content, XmlElementEndTag(name)); } diff --git a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs index 8cdf24f878efb..bd1ddb187daee 100644 --- a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs @@ -2874,10 +2874,12 @@ public void TestDocumentationComment() DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("This class provides extension methods for the "), SyntaxFactory.XmlSeeElement( SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), - SyntaxFactory.XmlText(" class.")), + SyntaxFactory.XmlText(" class."), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlThreadSafetyElement(), SyntaxFactory.XmlNewLine("\r\n"), @@ -2898,7 +2900,9 @@ public void TestXmlSummaryElement() DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This class provides extension methods."))); + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("This class provides extension methods."), + SyntaxFactory.XmlNewLine("\r\n"))); var actual = documentationComment.ToFullString(); @@ -2915,13 +2919,15 @@ public void TestXmlSeeElementAndXmlSeeAlsoElement() DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("This class provides extension methods for the "), SyntaxFactory.XmlSeeElement( SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), SyntaxFactory.XmlText(" class and the "), SyntaxFactory.XmlSeeAlsoElement( SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName2"))), - SyntaxFactory.XmlText(" class."))); + SyntaxFactory.XmlText(" class."), + SyntaxFactory.XmlNewLine("\r\n"))); var actual = documentationComment.ToFullString(); @@ -2944,11 +2950,15 @@ public void TestXmlNewLineElement() DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This is a summary.")), - SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("This is a summary."), + SyntaxFactory.XmlNewLine("\r\n")), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlRemarksElement( SyntaxFactory.XmlNewLine("\r\n"), - SyntaxFactory.XmlRemarksElement()); + SyntaxFactory.XmlNewLine("\r\n"))); var actual = documentationComment.ToFullString(); @@ -2968,7 +2978,9 @@ public void TestXmlParamAndParamRefElement() DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlParamRefElement("b")), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlParamRefElement("b"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("a"), SyntaxFactory.XmlNewLine("\r\n"), @@ -2992,10 +3004,14 @@ public void TestXmlReturnsElement() "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlReturnsElement( - SyntaxFactory.XmlText("Returns a value."))); + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("Returns a value."), + SyntaxFactory.XmlNewLine("\r\n"))); var actual = documentationComment.ToFullString(); @@ -3015,12 +3031,16 @@ public void TestXmlRemarksElement() "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("Same as in class "), SyntaxFactory.XmlSeeElement(SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName("TypeName"))), - SyntaxFactory.XmlText("."))); + SyntaxFactory.XmlText("."), + SyntaxFactory.XmlNewLine("\r\n"))); var actual = documentationComment.ToFullString(); @@ -3038,7 +3058,9 @@ public void TestXmlExceptionElement() "/// This exception will be thrown if the object is in an invalid state when calling this method."; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlExceptionElement( SyntaxFactory.TypeCref( @@ -3061,7 +3083,9 @@ public void TestXmlPermissionElement() "/// Needs MyPermission to execute."; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPermissionElement( SyntaxFactory.TypeCref( diff --git a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb index 1e02c46ddb1b3..7a45c818a1919 100644 --- a/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb +++ b/src/Compilers/VisualBasic/Portable/Syntax/SyntaxFactory.vb @@ -812,7 +812,7 @@ Namespace Microsoft.CodeAnalysis.VisualBasic ''' The name of the xml element. ''' A list of syntax nodes that represents the content of the xml multi line element. Public Shared Function XmlMultiLineElement(name As XmlNameSyntax, content As SyntaxList(Of XmlNodeSyntax)) As XmlElementSyntax - Return XmlElement(XmlElementStartTag(name), content.Insert(0, XmlNewLine("\r\n")).Add(XmlNewLine("\r\n")), XmlElementEndTag(name)) + Return XmlElement(XmlElementStartTag(name), content, XmlElementEndTag(name)) End Function ''' diff --git a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb index a87e4ab35df47..b1a5e33184010 100644 --- a/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb +++ b/src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb @@ -562,11 +562,13 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("This class provides extension methods for the "), SyntaxFactory.XmlSeeElement( SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("TypeName"))), - SyntaxFactory.XmlText(" class.")), + SyntaxFactory.XmlText(" class."), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlThreadSafetyElement(), SyntaxFactory.XmlNewLine("\r\n"), @@ -588,7 +590,9 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This class provides extension methods."))) + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("This class provides extension methods."), + SyntaxFactory.XmlNewLine("\r\n"))) Dim actual = documentationComment.ToFullString() @@ -606,6 +610,7 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("This class provides extension methods for the "), SyntaxFactory.XmlSeeElement( SyntaxFactory.CrefReference( @@ -614,7 +619,8 @@ End Module SyntaxFactory.XmlSeeAlsoElement( SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("TypeName2"))), - SyntaxFactory.XmlText(" class."))) + SyntaxFactory.XmlText(" class."), + SyntaxFactory.XmlNewLine("\r\n"))) Dim actual = documentationComment.ToFullString() @@ -637,11 +643,15 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlText("This is a summary.")), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("This is a summary."), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlNewLine("\r\n"), - SyntaxFactory.XmlRemarksElement()) + SyntaxFactory.XmlRemarksElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n"))) Dim actual = documentationComment.ToFullString() @@ -661,7 +671,9 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( - SyntaxFactory.XmlParamRefElement("b")), + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlParamRefElement("b"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlParamElement("a"), SyntaxFactory.XmlNewLine("\r\n"), @@ -685,10 +697,14 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlReturnsElement( - SyntaxFactory.XmlText("Returns a value."))) + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlText("Returns a value."), + SyntaxFactory.XmlNewLine("\r\n"))) Dim actual = documentationComment.ToFullString() @@ -708,14 +724,18 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlRemarksElement( + SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlText("Same as in class "), SyntaxFactory.XmlSeeElement( SyntaxFactory.CrefReference( SyntaxFactory.ParseTypeName("TypeName"))), - SyntaxFactory.XmlText("."))) + SyntaxFactory.XmlText("."), + SyntaxFactory.XmlNewLine("\r\n"))) Dim actual = documentationComment.ToFullString() @@ -733,7 +753,9 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlExceptionElement( SyntaxFactory.CrefReference( @@ -756,7 +778,9 @@ End Module Dim documentationComment As DocumentationCommentTriviaSyntax = SyntaxFactory.DocumentationComment( - SyntaxFactory.XmlSummaryElement(), + SyntaxFactory.XmlSummaryElement( + SyntaxFactory.XmlNewLine("\r\n"), + SyntaxFactory.XmlNewLine("\r\n")), SyntaxFactory.XmlNewLine("\r\n"), SyntaxFactory.XmlPermissionElement( SyntaxFactory.CrefReference( From e2c16d719e51a64bdf032028d08f30d358e803c4 Mon Sep 17 00:00:00 2001 From: robinsedlaczek Date: Wed, 6 Jan 2016 16:22:27 +0100 Subject: [PATCH 12/13] Replace new lines with explicit new line sequence "\r\n" in unit tests. --- .../Syntax/LexicalAndXml/XmlDocCommentTests.cs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs index bd1ddb187daee..0c7e528314306 100644 --- a/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs +++ b/src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs @@ -2894,9 +2894,10 @@ public void TestDocumentationComment() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlSummaryElement() { - var expected = @"/// -/// This class provides extension methods. -/// "; + var expected = + "/// \r\n" + + "/// This class provides extension methods.\r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( @@ -2913,9 +2914,10 @@ public void TestXmlSummaryElement() [Trait("Feature", "Xml Documentation Comments")] public void TestXmlSeeElementAndXmlSeeAlsoElement() { - var expected = @"/// -/// This class provides extension methods for the class and the class. -/// "; + var expected = + "/// \r\n" + + "/// This class provides extension methods for the class and the class.\r\n" + + "/// "; DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment( SyntaxFactory.XmlSummaryElement( From be901a1e93d19e3841f773956c7fec8677f0b2e9 Mon Sep 17 00:00:00 2001 From: Robin Sedlaczek Date: Thu, 14 Jan 2016 15:29:40 +0100 Subject: [PATCH 13/13] Change file mode. --- build/scripts/tests.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 build/scripts/tests.sh diff --git a/build/scripts/tests.sh b/build/scripts/tests.sh old mode 100644 new mode 100755