Enable source generators to augment XML comments

[stephentoub]

It's becoming an increasingly common approach for a source generator to fill in a partial method definition: the user writes a partial method without a body, and the source generator writes one with the body. However, the source generator is unable to augment the XML comments for that method. If the user puts their own XML comments on their partial declaration, then if the source generator does as well on its definition, the source generator's XML comments either replace the developers (bad) or are ignored (bad). There does not appear to be a way for a source generator to add to the comments, e.g. additional remarks or examples or any other content that's actually visible for the user in Visual Studio.

cc: @RikkiGibson

[RikkiGibson]

I am actually surprised to hear this. The doc comment processing code is pretty geared around the possibility that documentation for a single symbol may be present across multiple declarations. This is the case for doc comments on types: SharpLab.

I suspect the reason this is lost on methods is somewhat an accident to how the symbols work. SharpLab.

I'll review the doc comments spec when I get a chance but my instinct here is to treat it as a bug-fix level change in the compiler.

cc @jaredpar @dotnet/roslyn-compiler for consideration.

[RikkiGibson]

Opened dotnet/roslyn#60725

[stephentoub]

I'll review the doc comments spec when I get a chance but my instinct here is to treat it as a bug-fix level change in the compiler.

Should I open an issue then on dotnet/roslyn about fixing the merging of comments on methods?

[RikkiGibson]

Yes, let's track and address it separately.

[stephentoub]

I opened dotnet/roslyn#60730.

[ThaDaVos]

Has anyone seen any update on this?