Improved XML documentation support in ReSharper and Rider

Having code with XML documentation is great, as it allows generating nice API documentation and provides useful help while writing code:

XML documentation class and parameter info

ReSharper 2017.2 and Rider 2017.2 EAP give us more tooling to organize XML documentation across inheritance hierarchies.

When creating a class library that provides XML documentation, we can make use of the element to inherit documentation from a base class or an interface. Consider the following code:

Should documentation be inherited from ITenantAware or IRepository in this case? If we leave our code like this, we’ll not get any documentation at all. We’ll have to specify which base class we want to inherit documentation from, using the cref attribute. A new inspection (and quick-fix) will help us provide proper API documentation to the users of our library. Note that ReSharper and Rider provide us with code completion for possible types to reference when we invoke Smart Completion (Ctrl+Alt+Space).
Invalid use of inheritdoc

Another code inspection will warn us when a derived class overrides documentation of its base class, and offers to add to the XML documentation:
Suggest adding inheritdoc element

Download ReSharper Ultimate 2017.2 now or check out Rider 2017.2 EAP! We’d love to hear your thoughts.

This entry was posted in How-To's and tagged , , , , , . Bookmark the permalink.

4 Responses to Improved XML documentation support in ReSharper and Rider

  1. GreenMoose says:

    Worth noting is that using may cause issues down the road when it comes to XMLdoc generation, since it is not part of the CSharp language (https://github.com/dotnet/csharplang/issues/313) thus not supported by e.g. swashbuckle/swagger for doc generation (https://github.com/domaindrivendev/Swashbuckle/issues/1000)

  2. Aleksey says:

    Thank you for great ide!
    btw about xml documentation: any chance to see resolution of this issue in near future?)
    https://youtrack.jetbrains.com/issue/RIDER-8796

  3. LordJZ says:

    And the first screenshot shows the god-awful R# tooltips. Seriously guys, it’s been 2 years. It should have been changed 2 weeks after VS 2015 preview. RSRP-447855

  4. Marco says:

    @LordJZ: I haven’t seen those tooltips in a while, but I agree that they’re pretty lackluster. I include the “Enhanced Tooltip” extension, which addresses this issue quite nicely.

Leave a Reply

Your email address will not be published. Required fields are marked *