{"action":"created","issue":{"url":"https://api.github.com/repos/dotnet/roslyn/issues/218","labels_url":"https://api.github.com/repos/dotnet/roslyn/issues/218/labels{/name}","comments_url":"https://api.github.com/repos/dotnet/roslyn/issues/218/comments","events_url":"https://api.github.com/repos/dotnet/roslyn/issues/218/events","html_url":"https://github.com/dotnet/roslyn/issues/218","id":56444012,"number":218,"title":"Improve SyntaxFactory for documentation comments","user":{"login":"sharwell","id":1408396,"avatar_url":"https://avatars.githubusercontent.com/u/1408396?v=3","gravatar_id":"","url":"https://api.github.com/users/sharwell","html_url":"https://github.com/sharwell","followers_url":"https://api.github.com/users/sharwell/followers","following_url":"https://api.github.com/users/sharwell/following{/other_user}","gists_url":"https://api.github.com/users/sharwell/gists{/gist_id}","starred_url":"https://api.github.com/users/sharwell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sharwell/subscriptions","organizations_url":"https://api.github.com/users/sharwell/orgs","repos_url":"https://api.github.com/users/sharwell/repos","events_url":"https://api.github.com/users/sharwell/events{/privacy}","received_events_url":"https://api.github.com/users/sharwell/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/dotnet/roslyn/labels/0%20-%20Backlog","name":"0 - Backlog","color":"CCCCCC"},{"url":"https://api.github.com/repos/dotnet/roslyn/labels/API","name":"API","color":"eb6420"},{"url":"https://api.github.com/repos/dotnet/roslyn/labels/Area-Compilers","name":"Area-Compilers","color":"5319e7"},{"url":"https://api.github.com/repos/dotnet/roslyn/labels/Feature%20Request","name":"Feature Request","color":"fc2929"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-02-03T21:58:09Z","updated_at":"2015-02-04T03:35:48Z","closed_at":null,"body":"This request is best described by a motivating example.\r\n\r\nIn a recent code fix, I wanted to add the following documentation comment to a class:\r\n\r\n```csharp\r\n/// <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/>\r\n```\r\n\r\nThis is the way I found to implement it:\r\n\r\n```csharp\r\nDocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationCommentTrivia(SyntaxKind.SingleLineDocumentationCommentTrivia)\r\n    .AddContent(\r\n        SyntaxFactory.XmlElement(\r\n            SyntaxFactory.XmlElementStartTag(SyntaxFactory.XmlName(\"summary\")),\r\n            SyntaxFactory.List<XmlNodeSyntax>()\r\n                .Add(\r\n                    SyntaxFactory.XmlText().AddTextTokens(\r\n                        SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList()),\r\n                        SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), \"This class provides extension methods for the \", \"This class provides extension methods for the \", SyntaxFactory.TriviaList())\r\n                            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior(\"/// \"))))\r\n                .Add(\r\n                    SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName(\"see\")).AddAttributes(\r\n                        SyntaxFactory.XmlCrefAttribute(\r\n                            SyntaxFactory.XmlName(\"cref\"),\r\n                            SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),\r\n                            SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat))),\r\n                            SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))\r\n                            .WithLeadingTrivia(SyntaxFactory.Whitespace(\" \"))))\r\n                .Add(\r\n                    SyntaxFactory.XmlText().AddTextTokens(\r\n                        SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), \" class.\", \" class.\", SyntaxFactory.TriviaList()),\r\n                        SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList()))),\r\n            SyntaxFactory.XmlElementEndTag(SyntaxFactory.XmlName(\"summary\"))\r\n                .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior(\"/// \"))),\r\n        SyntaxFactory.XmlText().AddTextTokens(SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList())),\r\n        SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName(\"threadsafety\"))\r\n            .AddAttributes(\r\n                SyntaxFactory.XmlTextAttribute(\r\n                    SyntaxFactory.XmlName(\"static\"),\r\n                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),\r\n                    SyntaxFactory.TokenList(SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), \"true\", \"true\", SyntaxFactory.TriviaList())),\r\n                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))\r\n                    .WithLeadingTrivia(SyntaxFactory.Whitespace(\" \")),\r\n                SyntaxFactory.XmlTextAttribute(\r\n                    SyntaxFactory.XmlName(\"instance\"),\r\n                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),\r\n                    SyntaxFactory.TokenList(SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), \"false\", \"false\", SyntaxFactory.TriviaList())),\r\n                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))\r\n                    .WithLeadingTrivia(SyntaxFactory.Whitespace(\" \")))\r\n            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior(\"/// \")),\r\n        SyntaxFactory.XmlText().AddTextTokens(SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList())),\r\n        SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName(\"preliminary\"))\r\n            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior(\"/// \")))\r\n    .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior(\"/// \"))\r\n    .WithTrailingTrivia(SyntaxFactory.EndOfLine(Environment.NewLine));\r\n```\r\n\r\nI then had to attach the comment to the `ClassDeclarationSyntax` using the following transform:\r\n\r\n```csharp\r\n.WithLeadingTrivia(SyntaxFactory.TriviaList(SyntaxFactory.Trivia(documentationComment)))\r\n```"},"comment":{"url":"https://api.github.com/repos/dotnet/roslyn/issues/comments/72784908","html_url":"https://github.com/dotnet/roslyn/issues/218#issuecomment-72784908","issue_url":"https://api.github.com/repos/dotnet/roslyn/issues/218","id":72784908,"user":{"login":"sharwell","id":1408396,"avatar_url":"https://avatars.githubusercontent.com/u/1408396?v=3","gravatar_id":"","url":"https://api.github.com/users/sharwell","html_url":"https://github.com/sharwell","followers_url":"https://api.github.com/users/sharwell/followers","following_url":"https://api.github.com/users/sharwell/following{/other_user}","gists_url":"https://api.github.com/users/sharwell/gists{/gist_id}","starred_url":"https://api.github.com/users/sharwell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sharwell/subscriptions","organizations_url":"https://api.github.com/users/sharwell/orgs","repos_url":"https://api.github.com/users/sharwell/repos","events_url":"https://api.github.com/users/sharwell/events{/privacy}","received_events_url":"https://api.github.com/users/sharwell/received_events","type":"User","site_admin":false},"created_at":"2015-02-04T03:35:48Z","updated_at":"2015-02-04T03:35:48Z","body":"I added a `XmlSyntaxFactory` class to my project in https://github.com/sharwell/OpenStackNetAnalyzers/commit/26875b7719985dc4a06b98bf98f7426da8e1bf6f, which allowed me to produce exactly the same output using this code:\r\n\r\n```csharp\r\nDocumentationCommentTriviaSyntax documentationComment = XmlSyntaxFactory.DocumentationComment(\r\n    XmlSyntaxFactory.MultiLineElement(\r\n        \"summary\",\r\n        XmlSyntaxFactory.List(\r\n            XmlSyntaxFactory.Text(\"This class provides extension methods for the \"),\r\n            XmlSyntaxFactory.EmptyElement(\"see\").AddAttributes(\r\n                XmlSyntaxFactory.CrefAttribute(SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat))))),\r\n            XmlSyntaxFactory.Text(\" class.\"))),\r\n    XmlSyntaxFactory.NewLine(),\r\n    XmlSyntaxFactory.EmptyElement(\"threadsafety\")\r\n        .AddAttributes(\r\n            XmlSyntaxFactory.TextAttribute(\"static\", \"true\"),\r\n            XmlSyntaxFactory.TextAttribute(\"instance\", \"false\")),\r\n    XmlSyntaxFactory.NewLine(),\r\n    XmlSyntaxFactory.EmptyElement(\"preliminary\"));\r\n```"}}