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.
Stefan Over commented
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
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:
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
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
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
+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.
Jonas Tingmose +1
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.
Please do as Jonas Tingmose suggests
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.
I've created a library InheritDoc to implement exactly this (see www.inheritdoc.io) until Visual Studio implements it.
I also second the comment from Jonas Tingmose ...
Niels Peter Gibe commented
I second the comment from Jonas Tingmose (April 12, 2017 15:10)
That would be really useful
Joshua Morgan commented
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
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
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.
This would be an excellent addition!!
James McCosh commented
Rob Siklos commented
@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.
Just copy the comments when you implement or override. That's the best flow. That saves time, encourages documentation, and allows changing of documentation should a class need a different value than an interface.