Merge pull request #6790 from robinsedlaczek/Issue-218

Improved SyntaxFactory for documentation comments (Issue #218)

src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt

@@ -52,10 +52,58 @@ 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.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.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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax
+static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlElement(string localName, Microsoft.CodeAnalysis.SyntaxList<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> content) -> Microsoft.CodeAnalysis.CSharp.Syntax.XmlElementSyntax
+static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlMultiLineElement(string localName, Microsoft.CodeAnalysis.SyntaxList<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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(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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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 text, string value) -> Microsoft.CodeAnalysis.SyntaxToken
+static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlTextLiteral(string value) -> 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
+static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.XmlValueElement(Microsoft.CodeAnalysis.SyntaxList<Microsoft.CodeAnalysis.CSharp.Syntax.XmlNodeSyntax> 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<TResult>.VisitLoadDirectiveTrivia(Microsoft.CodeAnalysis.CSharp.Syntax.LoadDirectiveTriviaSyntax node) -> TResult

src/Compilers/CSharp/Test/Syntax/LexicalAndXml/XmlDocCommentTests.cs

@@ -2861,7 +2861,246 @@ public class Program
                 Diagnostic(ErrorCode.WRN_XMLParseError, " "));
         }
 
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestDocumentationComment()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// This class provides extension methods for the <see cref=\"TypeName\"/> class.\r\n" +
+                "/// </summary>\r\n" +
+                "/// <threadsafety static=\"true\" instance=\"false\"/>\r\n" +
+                "/// <preliminary/>";
+
+            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.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlThreadSafetyElement(),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlPreliminaryElement());
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlSummaryElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// This class provides extension methods.\r\n" +
+                "/// </summary>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlText("This class provides extension methods."),
+                    SyntaxFactory.XmlNewLine("\r\n")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlSeeElementAndXmlSeeAlsoElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" + 
+                "/// This class provides extension methods for the <see cref=\"TypeName\"/> class and the <seealso cref=\"TypeName2\"/> class.\r\n" +
+                "/// </summary>";
+
+            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.XmlNewLine("\r\n")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlNewLineElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// This is a summary.\r\n" +
+                "/// </summary>\r\n" +
+                "/// \r\n" +
+                "/// \r\n" +
+                "/// <remarks>\r\n" +
+                "/// \r\n" +
+                "/// </remarks>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    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.XmlNewLine("\r\n")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlParamAndParamRefElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// <paramref name=\"b\"/>\r\n" +
+                "/// </summary>\r\n" +
+                "/// <param name=\"a\"></param>\r\n" +
+                "/// <param name=\"b\"></param>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlParamRefElement("b"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlParamElement("a"),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlParamElement("b"));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlReturnsElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// \r\n" +
+                "/// </summary>\r\n" +
+                "/// <returns>\r\n" +
+                "/// Returns a value.\r\n" +
+                "/// </returns>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlReturnsElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlText("Returns a value."),
+                    SyntaxFactory.XmlNewLine("\r\n")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlRemarksElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// \r\n" +
+                "/// </summary>\r\n" +
+                "/// <remarks>\r\n" +
+                "/// Same as in class <see cref=\"TypeName\"/>.\r\n" +
+                "/// </remarks>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                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.XmlNewLine("\r\n")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlExceptionElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// \r\n" +
+                "/// </summary>\r\n" +
+                "/// <exception cref=\"InvalidOperationException\">This exception will be thrown if the object is in an invalid state when calling this method.</exception>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"), 
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                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<string>(expected, actual);
+        }
+
+        [Fact]
+        [Trait("Feature", "Xml Documentation Comments")]
+        public void TestXmlPermissionElement()
+        {
+            var expected = 
+                "/// <summary>\r\n" +
+                "/// \r\n" +
+                "/// </summary>\r\n" +
+                "/// <permission cref=\"MyPermission\">Needs MyPermission to execute.</permission>";
+
+            DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlPermissionElement(
+                    SyntaxFactory.TypeCref(
+                        SyntaxFactory.ParseTypeName("MyPermission")),
+                    SyntaxFactory.XmlText("Needs MyPermission to execute.")));
+
+            var actual = documentationComment.ToFullString();
+
+            Assert.Equal<string>(expected, actual);
+        }
+
         #region Xml Test helpers
+
         /// <summary>
         /// Verifies that the errors on the given CSharpSyntaxNode match the expected error codes and types
         /// </summary>

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)
         {

src/Compilers/VisualBasic/Portable/PublicAPI.Unshipped.txt

@@ -16,5 +16,50 @@ Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions.WithPublicSign(
 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
+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(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
+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(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
+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
 Shared Microsoft.CodeAnalysis.VisualBasic.SyntaxFactory.IsCompleteSubmission(tree As Microsoft.CodeAnalysis.SyntaxTree) -> Boolean
-Shared Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation.CreateScriptCompilation(assemblyName As String, syntaxTree As Microsoft.CodeAnalysis.SyntaxTree = Nothing, references As System.Collections.Generic.IEnumerable(Of Microsoft.CodeAnalysis.MetadataReference) = Nothing, options As Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions = Nothing, previousScriptCompilation As Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation = Nothing, returnType As System.Type = Nothing, globalsType As System.Type = Nothing) -> Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation
\ No newline at end of file
+Shared Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation.CreateScriptCompilation(assemblyName As String, syntaxTree As Microsoft.CodeAnalysis.SyntaxTree = Nothing, references As System.Collections.Generic.IEnumerable(Of Microsoft.CodeAnalysis.MetadataReference) = Nothing, options As Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilationOptions = Nothing, previousScriptCompilation As Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation = Nothing, returnType As System.Type = Nothing, globalsType As System.Type = Nothing) -> Microsoft.CodeAnalysis.VisualBasic.VisualBasicCompilation

src/Compilers/VisualBasic/Test/Syntax/Parser/XmlDocComments.vb

@@ -549,4 +549,247 @@ End Module
         </errors>)
     End Sub
 
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestDocumentationComment()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' This class provides extension methods for the <see cref=""TypeName""/> class.\r\n" &
+            "''' </summary>\r\n" &
+            "''' <threadsafety static=""true"" instance=""false""/>\r\n" &
+            "''' <preliminary/>"
+
+        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.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlThreadSafetyElement(),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlPreliminaryElement())
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlSummaryElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' This class provides extension methods.\r\n" &
+            "''' </summary>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlText("This class provides extension methods."),
+                    SyntaxFactory.XmlNewLine("\r\n")))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlSeeElementAndXmlSeeAlsoElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' This class provides extension methods for the <see cref=""TypeName""/> class and the <seealso cref=""TypeName2""/> class.\r\n" &
+            "''' </summary>"
+
+        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 and the "),
+                    SyntaxFactory.XmlSeeAlsoElement(
+                        SyntaxFactory.CrefReference(
+                            SyntaxFactory.ParseTypeName("TypeName2"))),
+                    SyntaxFactory.XmlText(" class."),
+                    SyntaxFactory.XmlNewLine("\r\n")))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlNewLineElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' This is a summary.\r\n" &
+            "''' </summary>\r\n" &
+            "''' \r\n" &
+            "''' \r\n" &
+            "''' <remarks>\r\n" &
+            "''' \r\n" &
+            "''' </remarks>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    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.XmlNewLine("\r\n")))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlParamAndParamRefElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' <paramref name=""b""/>\r\n" &
+            "''' </summary>\r\n" &
+            "''' <param name=""a""></param>\r\n" &
+            "''' <param name=""b""></param>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlParamRefElement("b"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlParamElement("a"),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlParamElement("b"))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlReturnsElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' \r\n" &
+            "''' </summary>\r\n" &
+            "''' <returns>\r\n" &
+            "''' Returns a value.\r\n" &
+            "''' </returns>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                SyntaxFactory.XmlReturnsElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlText("Returns a value."),
+                    SyntaxFactory.XmlNewLine("\r\n")))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlRemarksElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' \r\n" &
+            "''' </summary>\r\n" &
+            "''' <remarks>\r\n" &
+            "''' Same as in class <see cref=""TypeName""/>.\r\n" &
+            "''' </remarks>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                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.XmlNewLine("\r\n")))
+
+        Dim actual = documentationComment.ToFullString()
+
+        Assert.Equal(Of String)(expected, actual)
+    End Sub
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlExceptionElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' \r\n" &
+            "''' </summary>\r\n" &
+            "''' <exception cref=""InvalidOperationException"">This exception will be thrown if the object is in an invalid state when calling this method.</exception>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                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
+
+    <Fact>
+    <Trait("Feature", "Xml Documentation Comments")>
+    Public Sub TestXmlPermissionElement()
+        Dim expected =
+            "''' <summary>\r\n" &
+            "''' \r\n" &
+            "''' </summary>\r\n" &
+            "''' <permission cref=""MyPermission"">Needs MyPermission to execute.</permission>"
+
+        Dim documentationComment As DocumentationCommentTriviaSyntax =
+            SyntaxFactory.DocumentationComment(
+                SyntaxFactory.XmlSummaryElement(
+                    SyntaxFactory.XmlNewLine("\r\n"),
+                    SyntaxFactory.XmlNewLine("\r\n")),
+                SyntaxFactory.XmlNewLine("\r\n"),
+                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