Inheriting XML comments from interfaces in C#

C#.NetVisual Studio-2010

C# 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.

See https://github.com/dotnet/csharplang/issues/313

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).

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
Questionu84sixView Question on Stackoverflow
Solution 1 - C#NofflsView Answer on Stackoverflow
Solution 2 - C#psaxtonView Answer on Stackoverflow
Solution 3 - C#Fredrik MörkView Answer on Stackoverflow
Solution 4 - C#KonardView Answer on Stackoverflow
Solution 5 - C#Andreas ReiffView Answer on Stackoverflow
Solution 6 - C#K JohnsonView Answer on Stackoverflow