Inheriting XML comments from interfaces in C#
C#.NetVisual Studio-2010C# Problem Overview
I was wondering if anyone knows how to link an interface xml comment to an implementation. The problem is that I want the base comments to come from my interface first. Example:
interface myinterface {
/// <summary>
/// Does something.
/// </summary>
void method1(string foo);
}
and then the implementation is:
public class myclass : myinterface {
public void method1(string foo) {
//do something...
}
}
So now if I hover over the method with my mouse after instantiating the object:
myclass foo = new myclass();
foo.method1("do something");
how can I make the comments appear in the hover popup? Is there some way I can link the interface comments to the implementation? I know there's a way in Java, but can't find the solution for C#.
Thanks
C# Solutions
Solution 1 - C#
Updated Answer:
Use the <inheritdoc />
-[Tag][2].
Old Answer:
Linking XML Comments is IMHO not possible, but you could use a tool like [GhostDoc][1] to copy the XML Comment from your Interface/Baseclass to the implementation/derived class.
[1]: http://submain.com/products/ghostdoc.aspx "GhostDoc" [2]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/inheritdoc
Solution 2 - C#
XMLDoc defines a tag <include />
for including comments from another file which has been around since Visual Studio 2003. The largest caveat is the referenced file should be a file containing only XMLDoc documentation, not another source file.
See the MSDN page for more details.
Solution 3 - C#
If you use GhostDoc it helps a lot with "transporting" the documentation from interfaces to the implementing code.
Solution 4 - C#
Looks like <inheritdoc/>
will get native support soon.
Solution 5 - C#
http://blog.x-tensive.com/2008/02/fixml.html
It is a postprocessor that has certain additional options where the original documentation system is lacking.
From the website:
Brief summary:
FiXml is post-processor of XML documentation produced by C# \ Visual Basic.Net. It addresses some of the most annoying cases related to writing XML documentation in these languages:
- No support for inheriting the documentation from base class or interface. I.e. a documentation for any overridden member should be written from scratch, although normally it’s quite desirable to inherit at least the part of it.
- No support for insertion of commonly used documentation templates, such as “This type is singleton - use its
property to get the only instance of it.”, or even “Initializes a new instance of class.”
Solution 6 - C#
I built a command line tool to post-process the XML documentation files adding support for the <inheritdoc/> tag.
While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.
See www.inheritdoc.io for more info (free version available).