search

consulo / consulo-csharp

Languages: C#
Apache License 2.0
50 stars 6 forks source link

Inheritance of XML documentation comments and support <inheritdoc/> tag #517

Open NIA opened 6 years ago

NIA commented 6 years ago

A feature request: understanding <inheritdoc/> tag. Documentation generators like Sandcastle support this (more info in this VS UserVoice thread and this SO answer), and recently ReSharper/Rider also added such feature and understand this tag, making quick documentation (Ctrl+Q) inheritable. See the announcement. image It is worth noting that ReSharper/Rider inherits documentation by default, even when <inheritdoc/> is not specified.

Besides quick documentation popup, when used on method with a cref= attribute, this also makes it easy to quickly navigate to same method in the super class with mouse, becuase it behaves exatcly as the cref= attribute of <see/> and <seealso/> tags: clicking on it navigates to that symbol image

Not a critical, but would be nice to have. Currently Consulo shows a warning and does not inherit documentation. image

VISTALL commented 6 years ago

Hello. I'm not sure about this tag. For me - it's a hack, which C# compiler is not support, and used only inside IDE

Thanks

VISTALL commented 6 years ago

For example - there no documentation about cref attribute, idk about other attributes

NIA commented 6 years ago

@VISTALL C# compiler does not support any of tags at all 😉 He does not know anything about them and just throws them away like other comments. All tags, including common ones like <see>, <param> and others means anything only for IDEs and for documentation generators like Sandcastle (FIY Microsoft suggests Sandcastle in MSDN, so it is not something underground).

Documentation for ` in Sandcastle help is here: http://ewsoftware.github.io/XMLCommentsGuide/html/86453FFB-B978-4A2A-9EB5-70E118CA8073.htm

NIA commented 6 years ago

Also in the comment to the SO answer I mentioned above someone mentions that Visual Studio 2017 inherits documentation by default just like R#, so even if we forget about <inheritdoc/>, the inheritance of docs by default can be considered as consensus – would be great to see at least this 😃 I reworded the title of issue to make it clearer

VISTALL commented 6 years ago

the inheritance of docs by default can be considered as consensus – would be great to see at least this 😃

This is i like more than unknown(by ms) documentation tag.

VISTALL commented 6 years ago

Added support for

the inheritance of docs by default can be considered as consensus – would be great to see at least this 😃

in nightly (build progress here https://ci.consulo.io/)