Search code examples
c#xml-commentsexplicit-interfaceexplicit-implementation

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


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.


Solution

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