XML Comments -- How do you comment explicitly implemented interfaces properly?

Question

Code:

public interface IFoo
{
    void Bar();
}

public class FooClass : IFoo
{
    /// <summary> ... </summary>
    /// <seealso cref="?"/> //How do you reference the IFoo.Bar() method
    public void Bar() { }

    /// <summary> ... </summary>
    /// <seealso cref="?"/> //How do you reference the standard Bar() method
    void IFoo.Bar() { }
}

My guess is:

<seealso cref="IFoo.Bar()"/> //Explicitly implemented interface method
<seealso cref="Bar()"/>      //Standard method

but, I'm not sure. The ECMA guide didn't help distinguish, so I guess I'm looking for assurance that my guess is correct.

Reposeful

Answer 1

A quick test with Sandcastle Help File Builder revealed that in the created documentation the link <seealso cref="IFoo.Bar()"/> points to the method in the interface and <seealso cref="Bar()"/> points to the method in the class. The documentation for the explicitly implemented method is inherited from the interface so you should actually point to the interface method anyway.

Edit: ReSharper also complains with <seealso cref="FooClass.IFoo.Bar()"/> and corrects it to be <seealso cref="IFoo.Bar()"/> which then points to the interface method, not the explicitly implemented one.

Burma

That's what I thought, but I wasn't 100% sure. Thanks for clarifying that. – Reposeful

So is there no way to reference the explicitly defined interface method through xml comments? – Begotten

Answer 2

Use <seealso cref="M:FooClass.IFoo#Bar"/>. This is the syntax used in the XML document comments file.

And don't forget to prefix the namespace for both the class and the interface. If FooClass and IFoo resided in FooNamespace, you'd have to write <seealso cref="M:FooNamespace.FooClass.FooNamespace#IFoo#Bar"/>. Methods with arguments need a fully qualified parameter list.

You won't get Intellisense for this. And the compiler won't complain if you got the syntax wrong. You'll need to test this with your document generator.

I tested this with sandcastle and it works, but it's too brittle to seriously use it.

Zebadiah