Roslyn: Improvements to documentation comments (that compilers output).

[dfkeenan]

Hi,

Please add <inheritdoc /> tag or similar:

I think it would be really handy if the compiler(s) when outputting the documentation XML file if it could use inherited documentation where available/requested. Though I am not sure what should be output if there is no documentation available.

Please add the ability to add documentation comments for Namespace/Assembly:

Currently if you want to do this for tools that generate documentation html etc. you have to add a dummy class and add the documentation comments to them. This one is a bit trickier because there aren't any viable options for doing them directly in code. There is nothing you could put the assembly documentation against in code and namespaces are "declared" possibly in multiple files. The only thing I could really think of is a separate XML file that gets merged into the documentation XML file that is output.

Cheers,
dfkeenan

P.S. A Diagnostic and Code Fix that generates document comments for me would also great :smiley:

[maxtoroq]

:+1: <inheritdoc/>

[matkoch]

Looking at how it works in Sandcastle, I would like to argue against having the select attribute, because it's very likely to change documentation unintentionally (e.g., select="para[last()]").

Some use cases:

• /// <inheritdoc /> copies all tags like summary, remarks and so on
• /// <inheritdoc /><summary><inheritdoc /> Additional text</summary> inherits all tags, except summary, which is re-declared, but also can inherit again
• /// <summary><inheritdoc cref="System.Exception" /></summary> in case there are multiple base classes/interfaces (apart from System.Object)

Still, open question for me is, what should happen if there are multiple immediate base types, but no cref specification... Leave the tag as is? Generate a warning?

[gafter]

This seems like a nice potential enhancement to the expressiveness of the doc facility.

[gafter]

We are now taking language feature discussion on https://github.com/dotnet/csharplang for C# specific issues, https://github.com/dotnet/vblang for VB-specific features, and https://github.com/dotnet/csharplang for features that affect both languages.

[drauch]

@gafter: Should we reopen the issue at https://github.com/dotnet/csharplang or do you think it is enough to have the docfx#1306 open?

[daveaglick]

@drauch @gafter DocFx is a separate tool and not part of the language or compiler. As the author of a .NET documentation tool I would really like to see support for <inheritdoc> exposed through the Roslyn XML documentation objects directly. I'm happy to reopen this over at csharplang if needed.

[gafter]

I think it would require language (and therefore compiler) support, so if you are still interested an issue at csharplang makes sense.

[drauch]

@daveaglick : Would love to see that 👍

[gafter]

This request is now tracked at https://github.com/dotnet/csharplang/issues/313