XML 注释——您如何正确地注释显式实现的接口？

Question

代码：

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() { }
}

我的猜测是：

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

但是，我不确定。 ECMA 指南没有帮助区分，所以我想我正在寻找我的猜测是正确的保证。

Answer 1

使用<seealso cref="M:FooClass.IFoo#Bar"/>。这是 XML 文档 cmets 文件中使用的语法。

并且不要忘记为类和接口的命名空间添加前缀。如果FooClass 和IFoo 驻留在FooNamespace 中，则必须写为<seealso cref="M:FooNamespace.FooClass.FooNamespace#IFoo#Bar"/>。带参数的方法需要一个完全限定的参数列表。

您不会为此获得 Intellisense。如果语法错误，编译器也不会抱怨。您需要使用文档生成器对此进行测试。

我用沙堡测试了这个，它可以工作，但它太脆，不能认真使用。

Answer 2

使用 Sandcastle Help File Builder 进行的快速测试显示，在创建的文档中，链接 <seealso cref="IFoo.Bar()"/> 指向接口中的方法，<seealso cref="Bar()"/> 指向类中的方法。显式实现方法的文档是从接口继承的，所以无论如何你都应该指向接口方法。

编辑：ReSharper 还抱怨 <seealso cref="FooClass.IFoo.Bar()"/> 并将其更正为 <seealso cref="IFoo.Bar()"/> 然后指向接口方法，而不是显式实现的方法。