c# - 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

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

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

Answer 2

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

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

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

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