Quick Info should merge elements with the same name

[RikkiGibson]

Related to dotnet/csharplang#6014

/// <summary>hi</summary>
/// <remarks>hello</remarks>
public partial class C {
}

/// <remarks>second</remarks>
public partial class C {
}

In the above scenario, Quick Info shows "hi" and "hello", but not "second". SharpLab

We confirmed that the compiler APIs do include both elements, so we think that Quick Info is "dropping" the second remarks tag here. Should Quick Info change to somehow merge these?

[sharwell]

I can't find any indication in the specification to suggest that multiple <remarks> section elements are expected on a single code element. Considering that this is likely going to not be portable across documentation generation tools, it seems like the current IDE behavior reflects one reasonable interpretation of the presented code.

If we do make a change here, it should be coordinated across both the IDE and the known tools which process documentation files.

[RikkiGibson]

I think at least we should reach a set of recommendations for whether/how source generators can add documentation to user-declared symbols. It would be useful to know if we already have analyzers to warn against certain duplicate elements.

[sharwell]

It would be useful to know if we already have analyzers to warn against certain duplicate elements.

There are very few analyzers for documentation in use today. The one mentioned here would be a good candidate for a portability rule in DotNetAnalyzers.DocumentationAnalyzers.

[KathleenDollard]

Just weighing in on an opinion here:

• We should merge different elements XML comments on partial methods aren't merged #60730
• We should follow prior art on whether to merge things with the same name and this is likely to be tag specific (how could you merge a summary)
• When there are conflicts, user code should win - either by being the only thing displayed or appearing first.