I suggest you ...

Add IntelliSense support for the <inheritdoc /> tag in XML documentation comments

We currently use the <inheritdoc /> and <inheritdoc cref="" /> tags extensively in our code base in order to reduce the amount of duplicated documentation that needs to be written.

This works great for the most part, since we generate our docs using Sandcastle.

However, when we are actually developing code in the same c# project as the API which uses <inheritdoc>, Visual Studio does not recognize the tag, or resolve any references.

It would be great if Visual Studio Intellisense could actually do this.

2,800 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    Rob Siklos shared this idea  ·   ·  Flag idea as inappropriate…  ·  Admin →

    31 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      Signed in as (Sign out)
      Submitting...
      • Rodrigo Olivares commented  ·   ·  Flag as inappropriate

        Even when I'm implementing the method I'd like to show a guidance from documentation made into the interface in order to complete the work. I'd like to see it in newer versions.

      • Stefan Over commented  ·   ·  Flag as inappropriate

        I'd really like to see this feature in the near future.
        It's painful to track duplicated documentation around everywhere!

      • Chris “Spikeh” Sebok commented  ·   ·  Flag as inappropriate

        Just ran into an issue with this. I use Resharper, which supports the <inheritdoc/> tag, but I'm also using Swagger UI with ASP.Net Core WebAPI - which essentially reads the generated XML files. The XML files look like this:

        <member name="P:MyNamespace.MyType.MyProperty">
        <inheritdoc/>
        </member>

        So Swagger just reads the <inheritdoc/> tag, as the file (rightly) provides no inheritance information.

        I would suggest that when XML files are generated and <inheritdoc/> is encountered, it should essentially read the inheritance chain and write the relevant help text to the file.

      • Brent Rittenhouse commented  ·   ·  Flag as inappropriate

        What's the hang up with this idea? It's honestly the ONE FEATURE that I've wanted since at least 2012. I'm not implying anyone is lazy or not listening, I'm assuming there must be some fundamental thing that I'm not thinking about that makes this hard to implement. =/ Couldn't we roll our own using Roslyn these days?

      • Joe Amenta commented  ·   ·  Flag as inappropriate

        I echo the support of others in this thread who promote automatically inferring the equivalent to <inheritdoc /> on members where xmldoc is totally absent, but that feels likely to be more expensive to develop.

        I would be perfectly content if this just applied to things with <inheritdoc /> on them, ideally the same way SHFB works.

        I could live with having it only work with explicit crefs as a first cut, since I know there are plenty of edge-cases that may complicate resolving bare <inheritdoc /> tags.

      • Felix Schröter commented  ·   ·  Flag as inappropriate

        +1 to Jonas Tingmose's suggestion.

        I'd really like a configuration where my style guide force all Interfaces (and non-inherited classes/members) do be documented and the actual implementation XMLDoc can optionally be overwritten.
        Thus I could remove many lines of redundant XMLDoc comments from my implementations.

      • Chris commented  ·   ·  Flag as inappropriate

        I have sought after this kind of documentation integration for many years. It is good to hear Sandcastle still exists. It sounds as though it is becoming more feasible.

      • Anonymous commented  ·   ·  Flag as inappropriate

        Surprised this is still something of an issue. I'm with what some others have said, add a inheritDoc (or similar) tag, and if no comment is provided for an overriding method, automatically inherit. Would make it much easier to maintain and understand code.

      • Joshua Morgan commented  ·   ·  Flag as inappropriate

        Even from the standpoint of parsing comments from the Interface to the Class would be useful here. I often find myself placing comments into the Interface as that is my point of contact. Yet when I operate on a Class object directly, IntelliSense documentation is lost. It would be beneficial for IntelliSense to draw those comments from the Interface even (if nothing else).

      • Olivier J. commented  ·   ·  Flag as inappropriate

        As @JonasTingmode states, xml-comments should automatically be inherited. In addition to this, there should be a get-xml-comment-from-base-or-interface-refactoring, in case want to refine the comment for concrete implementations.

      • Jonas Tingmose commented  ·   ·  Flag as inappropriate

        Why stop there? Why even need to type in <inheritdoc /> everywhere? If no new XML documentation has been written for the overriding function, then just show the XML-comments from the base-function. You could just use the <remarks> tag to sort of add on information to the overriding function, should there be any. And if you absolutely HAVE to write a new summary, then just do that, and then the XML-comments from the base function will NOT be inherited.

        How is this not the way? How is there not one person, who has written a simple plugin to do this? Not even Resharper does this. If I had time to get into making plugins for VS, this would be my first.

      • Rob Siklos commented  ·   ·  Flag as inappropriate

        @Ryan: That is certainly not the best flow. If a class implements an interface, then the interface documentation is the "contract", and that must be correct. If the interface documentation changes, developers can't be expected to find all the implementations and duplicate those changes in the implementation's doc. DRY principle anyone? The whole point of inheritdoc in the first place is to avoid having to do those kinds of things.

        If the class needs a different value that what's coming from the interface, that's perfectly fine, and perfectly allowable when using inheritdoc - specific parts can be inherited and/or overridden.

      ← Previous 1

      Feedback and Knowledge Base