Is there a preferred way to document methods implementing an interface?

Question

I wonder if there's some way of doing this, or even if it should be done? My thoughts soon went to using method attributes as it's a kind of metadata, but I'm unsure if there are any for this purpose. Right now, I'm simply using XML comment <remark> tags to tell when a method implements some interface. But this is of course no structured form of metadata at all.

Maybe automated code documentation systems can already parse this information through the code, but it could still be useful for anyone reading the actual code to follow it more easily.

Answer 1

If you mean something like a list of classes that implement an interface, you could use the <seealso> tag of the documentation header.

/// <summary>
/// Interface that AutoCAD commands are required to implement.
/// </summary>
/// <seealso cref="My.Namespace.ClassThatImplementsThisInterface"/>
/// <seealso cref="My.Namespace.AnotherClassThatImplementsThisInterface"/>
public interface IMyInterface

You could also do this on a method to refer back to the interface method:

public class ClassThatImplementsThisInterface : IMyInterface
{
    /// <summary>
    /// </summary>
    /// <seealso cref="My.Namespace.IMyInterface.InterfaceMethod" />
    public void InterfaceMethod()
    {
    }
}

I've only ever used one documentation generator in C# and didn't use the above methods at the time so I cannot say this for granted, but I believe generators should pick up these references and create a link in the documentation to the referenced method/class/interface.

Answer 2

Have a look at GhostDoc. Its a free visual studio plugin. It has menu and easy keyboard shortcuts to automatically generate the documentation comments. It will also be smart enough to infer some functionality from the names of methods. For example, if you have method such as "public void SavePerson()", when inside the method, you press Ctrl+Shift+D and it will generate the comments prefilled with something like "this method is used to Save a Person".

If your class implements an interface, it will document that too. If you methods take parameters, it will cross reference those types.

You will still need to type plenty of text to add value to what it is your class/method/property actually does, but GhostDoc is a great way to generate the basic scaffolding, cross references, inheritance hierarchy and interface details in code documentation.