Ways to synchronize interface and implementation comments in C#

Question

Are there automatic ways to sync comments between an interface and its implementation? I'm currently documenting them both and wouldn't like to manually keep them in sync.

UPDATE:

Consider this code:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

When I create class like this:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Here comments are not shown:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

The <inheritDoc/> tag will perfectly generate the documentation in Sand Castle, but it doesn't work in intellisense tooltips.

Please share your ideas.

Thanks.

Answer 1

Don't do that. Think of it this way - if both comments are required to be the same all the time, then one of them isn't necessary. There has to be a reason for the comment (besides some kind of weird obligation to comment-block every function and variable) so you need to figure out what that unique reason is and document that.

Answer 2

I usually write comments like this:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

The methods are used only by the interface, so this comment is not even shown in tooltips when coding.

Edit:

If you want to see docs when you call the class directly and not using the interface, you need to write it twice or use a tool like GhostDoc.

Answer 3

Try GhostDoc! It works for me :-)

Edit: Now that I've been made aware of Sandcastle's support for <inheritdoc/>, I endorse Noldorin's post. It's a much better solution. I still recommend GhostDoc on a general basis, though.

Answer 4

You can do this quite easily using the Microsoft Sandcastle (or NDoc) inheritdoc tag. It's not officially supported by the specification, but custom tags are perfectly acceptable, and indeed Microsoft chose to copy this (and one or two other tags) from NDoc when they created Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Here is the help page from the Sandcastle Help File Builder GUI, which describes its usage in full.

(Of course, this isn't specifically "synchronisation", as your question mentions, but it would seem to be exactly what you're looking for nonetheless.)

As a note, this sounds like a perfectly fair idea to me, though I've observed that some people think you should always respecify comments in derived and implemented classes. (I've actually done it myself in documenting one of my libraries and I haven't see any problems whatsoever.) There's almost always no reason for the comments to differ at all, so why not just inherit and do it the easy way?

Edit: Regarding your update, Sandcastle can also take care of that for you. Sandcastle can output a modified version of the actual XML file it uses for input, which means you can distribute this modified version along with your library DLL instead of the one built directly by Visual Studio, which means you have the comments in intellisense as well as the documentation file (CHM, whatever).

Answer 5

/// <inheritDoc/>

Read here

Use this

Answer 6

With ReSharper you can copy it, but I don't think that it is in sync all the time.

Answer 7

This is one reason I like explicit implementation of interfaces, since it 'forces' the use of the interface.

Answer 8

I have a better answer: FiXml.

Cloning the is certainly working approach, but it has significant disadvantages, e.g.:

• When the original comment is changed (which frequently happens during development), its clone is not.
• You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.

As it was mentioned, there is <inheritdoc> tag in Sandcastle, but it has few disadvantages in comparison to FiXml:

• Sandcastle produces compiled HTML help files - normally it does not modify .xml files containing extracted XML comments (at last, this can't be done "on the fly" during the compilation).
• Sandcastle's implementation is less powerful. E.g. the is no <see ... copy="true" />.

See Sandcastle's <inheritdoc> description for further details.

Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few 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 <see cref="Instance" /> property to get the only instance of it.”, or even “Initializes a new instance of <CurrentType> class.”

To solve mentioned issues, the following additional XML tags are provided:

• <inheritdoc />, <inherited /> tags
• <see cref="..." copy="..." /> attribute in <see/> tag.

Here is its web page and download page.