Confusing code generated for XML elements in documentation comments

[svick]

Consider a member with XML documentation comment:

/// <summary></summary>
int i;

The relevant section of code generated for the XML comment is:

XmlExampleElement()
.WithStartTag(
    XmlElementStartTag(
        XmlName(
            Identifier("summary"))))
.WithEndTag(
    XmlElementEndTag(
        XmlName(
            Identifier("summary"))))

Notice how the code first creates an <example> element and then overwrites both tags with the right name. That's not technically wrong, but it's certainly a confusing way to create the tree.

Ideally, RoslynQuoter should use a specific factory method, when one is available (in this case, XmlSummaryElement). Though always using the generic XmlElement method would be fine too.

[KirillOsenkov]

Unfortunately the algorithm breaks down when there's more than one way to create the given tree. It works so well in general because usually there's only a single method that can create a node of the desired type, so there's no ambiguity.

However Xml factory methods were added later, and they have a few convenience methods, so the algorithm just chooses the first one that works, and that explains the results above.

We'd need some heuristics to fine tune this behavior and provide hints to the algorithm on a case-by-case basis.

[KirillOsenkov]

See here for details:

RoslynQuoter/src/Quoter/Quoter.cs

Line 897 in d2fd4be

// In this commit: https://github.com/dotnet/roslyn/commit/4c19f1b28df66eaf3035105ec5b8bb35bfeb6869

I'm not sure how to add such a heuristic, perhaps we can have "factoryMethodsToPrefer", so we can disambiguate here:

RoslynQuoter/src/Quoter/Quoter.cs

Line 1069 in d2fd4be

factory = candidatesWithMinParameterCount[0];