Comment Inheritance for C# (actually any language)

问题:

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!

回答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"

回答2:

You can always use <inheritdoc /> tag.

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

回答3:

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

回答4:

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

回答5:

Resharper has an option to copy the comments from the base class or interface.

回答6:

Another way is to use the XML doc tag. This is some extra effort but works out of the box...

Here are some examples:

    /// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

Update:

I now prefer to use /// <inheritdoc/> which is now supported by ReSharper.

回答7:

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

回答8:

I ended up creating a tool to post-process the XML documentation files to add support for replacing the <inheritdoc/> tag in the XML documentation files themselves. Available at www.inheritdoc.io (free version available).