Inheriting comments from an interface in an implementing class?

Question

Suppose I have this interface

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

And this class

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

Is there a way, or is there a tool that can let me automatically put in the comments of each member in a base class or interface?

Because I hate re-writing the same comments for each derived sub-class!

Solution 1

GhostDoc does exactly that. For methods which aren't inherited, it tries to create a description out of the name.

FlingThing() becomes "Flings the Thing"

Solution 2

You can always use the <inheritdoc /> tag:

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

Using the cref attribute, you can even refer to an entirely different member in an entirely different class or namespace!

public class Foo
{
    /// <inheritdoc cref="System.String.IndexOf" />
    public void Bar() { ... } // this method will now have the documentation of System.String.IndexOf
}

Solution 3

Use /// <inheritdoc/> if you want inheritance. Avoid GhostDoc or anything like that.

I agree it is annoying that comments are not inherited. It would be a fairly simple add-in to create if someone had the time (i wish i did).

That said, in our code base we put XML comments on the interfaces only and add extra implementation comments to the class. This works for us as our classes are private/internal and only the interface is public. Any time we use the objects via the interfaces we have full comments display in intellisence.

GhostDoc is good start and has made the process easier to write comments. It is especially useful keeping comments up-to-date when you add/remove parameters, re-run GhostDoc and it will update the description.

Solution 4

I would say to directly use the

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

And

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

You have to put this comments just on the previous line of your class/method

This will get the info of your comments for example from an interface that you have documented like :

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Solution 5

Java has this, and I use it all the time. Just do:

/**
 * {@inheritDoc}
 */

And the Javadoc tool figures it out.

C# has similar marker:

<inheritDoc/>

You can read more here:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

View more solutions

Comments

[Olivier Jacot-Descombes]

I not only hate it but it is also difficult to keep them in sync.

[Ellis Shen]

GhostDoc is awesome, one of those things that I didn't know I needed but now can't do without :o)

[gerleim]

I didn't know <inheritdoc /> even exist... But as far as I can see, the comment for this method doesn't show up with intellisense.

[Eric Dand]

C# does not have the <inheritdoc/> marker: Sandcastle has it. shfb.codeplex.com

[rbwhitaker]

@gerleim Look at Jeff Heaton's answer from a year earlier, and the comment below it. Sandcastle has <inheritdoc/>, not C#.

[Lensflare]

Automatically generated docs seem like a very bad idea to me. They don't add any useful information but only blow up the code unnecessarily. If a tool can understand what a method does from its name, than a person can also understand and no doc is needed.

[itmuckel]

@Lensflare This is so true. I once had to use a framework which had only such generated comments, that added NO information to the method/class. Instead of "This method does this and that" the comments where like "This is method XY of class Z". xD Also you coudn't browse the code, so it went down to trial&error. Never again! :-)

[Jazimov]

Oh? How? I use ReSharper and I never saw that option when implementing or inheriting an interface... Where is it and how do you use that option?

[svick]

@Jazimov When you Alt+Enter the override method, there is an option to "Copy documentation from base".

[Matt]

I see comments from the interface in intellisense with inheritdoc, and also if there's no code-doc at all on the derived class. But that could be because I have resharper.

[James Curran]

Neither C# nor Java (nor any other programming language) has any of the "XML doc" elements. These are comments. The compilers know nothng about them. They are all strict used by third-party documentation generators, whether that is javadoc or sandcastle or whatever.

[Horcrux7]

In Rider I see also comments from the interface in intellisense with inheritdoc, and also if there's no code-doc.

[JeffHeaton]

When Java or C# is stated, it USUALLY means the community of associated tools. Neither Java nor C# have much ability in the very literal sense. It would be an academic argument to state that Java or C# lack the ability to connect to a database, because the run time library does that.

[Dav Evans]

Resharper 2017.2 has improved support for inheritdoc jetbrains.com/resharper/whatsnew

[CosmicGiant]

@Lensflare While I 100% agree with you as far as relying on the AGDs as is, I should point out that AGDs are not meant to be used as "do it all" magic buttons like that. Instead, they are meant to be used as template-generators to reduce the amount of boilerplate, repetitive documentation you have to write yourself, so you can focus on the important stuff. --- For example, it can generate the <summary>, <param>, <returns>, <throws>, etc... sections for you. Many times with good-enough results; other times needing corrections or expanding, but still reducing overall effort.

[Trident D'Gao]

people the documentation isn't for developers it's for architects so their butts are all covered: "Hey, can we read the code documentation of your project? Sure, here it is."

[Douglas Gaskell]

VS2017 Professional shows inherited comments for me.

[herzbube]

Visual Studio Enterprise 2017 (version 15.9.3) does not show inherited comments for me.

[Reven]

That is strange but I can see comments from interface even without inheridoc. (VS Enterprise 2017 15.7.6)

[ashbygeek]

Visual Studio version 16.4.0 and newer provide intellisense for this notation! docs.microsoft.com/en-us/visualstudio/releases/2019/…

[ashbygeek]

Visual Studio version 16.4.0 and newer provide intellisense for <inheritDoc/>! docs.microsoft.com/en-us/visualstudio/releases/2019/…

[Mike Marynowski]

I'm confused - you said avoid GhostDoc, but at the end there you seemingly endorsed GhostDoc helping make things easier. Can you clarify what you mean?

[Dennis]

Thanks @MikeMarynowski. This is old advice. I think I wanted to say at the time that GhostDoc, like any other generator, will add comments but with almost useless detail e.g. <param name="origin">The origin.</param>. See ghostdoc says the damndest things for more examples. Visual Studio now has much better linting and generators for xmldocs to let you know when parameters + docs don't align so GhostDoc (or other tools) aren't needed anymore.

[Denis Babarykin]

Thanks for advice! This approach is more explicit and solves the problem of inheritance class description from object class (even when implementing interface).