Improve SyntaxFactory for documentation comments

[sharwell]

This request is best described by a motivating example.

In a recent code fix, I wanted to add the following documentation comment to a class:

/// <summary>
/// This class provides extension methods for the <see cref="TypeName"/> class.
/// </summary>
/// <threadsafety static="true" instance="false"/>
/// <preliminary/>

This is the way I found to implement it:

DocumentationCommentTriviaSyntax documentationComment = SyntaxFactory.DocumentationCommentTrivia(SyntaxKind.SingleLineDocumentationCommentTrivia)
    .AddContent(
        SyntaxFactory.XmlElement(
            SyntaxFactory.XmlElementStartTag(SyntaxFactory.XmlName("summary")),
            SyntaxFactory.List<XmlNodeSyntax>()
                .Add(
                    SyntaxFactory.XmlText().AddTextTokens(
                        SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList()),
                        SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), "This class provides extension methods for the ", "This class provides extension methods for the ", SyntaxFactory.TriviaList())
                            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior("/// "))))
                .Add(
                    SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName("see")).AddAttributes(
                        SyntaxFactory.XmlCrefAttribute(
                            SyntaxFactory.XmlName("cref"),
                            SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),
                            SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat))),
                            SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))
                            .WithLeadingTrivia(SyntaxFactory.Whitespace(" "))))
                .Add(
                    SyntaxFactory.XmlText().AddTextTokens(
                        SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), " class.", " class.", SyntaxFactory.TriviaList()),
                        SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList()))),
            SyntaxFactory.XmlElementEndTag(SyntaxFactory.XmlName("summary"))
                .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior("/// "))),
        SyntaxFactory.XmlText().AddTextTokens(SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList())),
        SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName("threadsafety"))
            .AddAttributes(
                SyntaxFactory.XmlTextAttribute(
                    SyntaxFactory.XmlName("static"),
                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),
                    SyntaxFactory.TokenList(SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), "true", "true", SyntaxFactory.TriviaList())),
                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))
                    .WithLeadingTrivia(SyntaxFactory.Whitespace(" ")),
                SyntaxFactory.XmlTextAttribute(
                    SyntaxFactory.XmlName("instance"),
                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken),
                    SyntaxFactory.TokenList(SyntaxFactory.XmlTextLiteral(SyntaxFactory.TriviaList(), "false", "false", SyntaxFactory.TriviaList())),
                    SyntaxFactory.Token(SyntaxKind.DoubleQuoteToken))
                    .WithLeadingTrivia(SyntaxFactory.Whitespace(" ")))
            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior("/// ")),
        SyntaxFactory.XmlText().AddTextTokens(SyntaxFactory.XmlTextNewLine(SyntaxFactory.TriviaList(), Environment.NewLine, Environment.NewLine, SyntaxFactory.TriviaList())),
        SyntaxFactory.XmlEmptyElement(SyntaxFactory.XmlName("preliminary"))
            .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior("/// ")))
    .WithLeadingTrivia(SyntaxFactory.DocumentationCommentExterior("/// "))
    .WithTrailingTrivia(SyntaxFactory.EndOfLine(Environment.NewLine));

I then had to attach the comment to the ClassDeclarationSyntax using the following transform:

.WithLeadingTrivia(SyntaxFactory.TriviaList(SyntaxFactory.Trivia(documentationComment)))

[sharwell]

I added a XmlSyntaxFactory class to my project in sharwell/OpenStackNetAnalyzers@26875b7, which allowed me to produce exactly the same output using this code:

DocumentationCommentTriviaSyntax documentationComment = XmlSyntaxFactory.DocumentationComment(
    XmlSyntaxFactory.MultiLineElement(
        "summary",
        XmlSyntaxFactory.List(
            XmlSyntaxFactory.Text("This class provides extension methods for the "),
            XmlSyntaxFactory.EmptyElement("see").AddAttributes(
                XmlSyntaxFactory.CrefAttribute(SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat))))),
            XmlSyntaxFactory.Text(" class."))),
    XmlSyntaxFactory.NewLine(),
    XmlSyntaxFactory.EmptyElement("threadsafety")
        .AddAttributes(
            XmlSyntaxFactory.TextAttribute("static", "true"),
            XmlSyntaxFactory.TextAttribute("instance", "false")),
    XmlSyntaxFactory.NewLine(),
    XmlSyntaxFactory.EmptyElement("preliminary"));

[sharwell]

I further simplified this by adding utility methods to XmlSyntaxFactory for common elements like <summary>, <remarks>, <see>, etc.: sharwell/OpenStackNetAnalyzers@ec77759

Now the code to create the desired comment looks like this:

DocumentationCommentTriviaSyntax documentationComment = XmlSyntaxFactory.DocumentationComment(
    XmlSyntaxFactory.SummaryElement(
        XmlSyntaxFactory.Text("This class provides extension methods for the "),
        XmlSyntaxFactory.SeeElement(
            SyntaxFactory.TypeCref(SyntaxFactory.ParseTypeName(declaringType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat)))),
        XmlSyntaxFactory.Text(" class.")),
    XmlSyntaxFactory.NewLine(),
    XmlSyntaxFactory.ThreadSafetyElement(),
    XmlSyntaxFactory.NewLine(),
    XmlSyntaxFactory.PreliminaryElement());

[robinsedlaczek]

I like to grap this!

[robinsedlaczek]

@sharwell Could you please review my first changes?

robinsedlaczek@4c19f1b

I have some question:

1. Was this the correct place for my changes?
2. Which code should be part of the internal syntax and which should be part of the SyntaxFactory?
3. Should some changes go to the auto-generated part of the SyntaxFactory?
4. Is it ok, that there are such abstraction in the SyntaxFactory that do not really correspond to *Syntax types resp. non-terminal symbols?
5. Where to write the unit tests? For now, I implemented one in SyntaxFactoryTests.cs. Is that the correct place?
6. What do you think about the naming of the methods? I decided to keep your name choice for the top level method "DocumentationComment". All other methods got the prefix "Xml". That is shorter the the prefix "DocumentationComment" what I had in mind at the beginning and it reflects the underlying syntax types more clear.

I would appreciate to get some information and guidance from you in order to complete the work. I will document all the methods and write appropriate test for them, before sending the PR.

Many thanks in advance!

[mattwar]

You can also simply use

SyntaxFactory.ParseTrivia(
@"/// <summary>
/// This class provides extension methods for the <see cref=""TypeName""/> class.
/// </summary>
/// <threadsafety static=""true"" instance=""false""/>
/// <preliminary/>");