Комментарии XML-Как правильно комментировать явно реализованные интерфейсы?

код:

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 не помогло отличить, поэтому я думаю, что я ищу уверенность в том, что моя догадка верна.

6
c# explicit-implementation explicit-interface xml-comments

2 ответов

быстрый тест с Sandcastle Help File Builder показал, что в созданной документации ссылка <seealso cref="IFoo.Bar()"/> указывает на метод в интерфейсе и <seealso cref="Bar()"/> указывает на метод в классе. Документация для явно реализованного метода наследуется от интерфейса, поэтому вы все равно должны указать на метод интерфейса.

Edit: ReSharper также жалуется на <seealso cref="FooClass.IFoo.Bar()"/> и исправляет его, чтобы быть <seealso cref="IFoo.Bar()"/>, который затем указывает на метод интерфейса, а не явно реализован один.

1

использовать <seealso cref="M:FooClass.IFoo#Bar"/>. Это синтаксис, используемый в файле комментариев XML-документа.

и не забудьте указать префикс пространства имен для класса и интерфейса. Если FooClass и IFoo проживал в FooNamespace, вы должны написать <seealso cref="M:FooNamespace.FooClass.FooNamespace#IFoo#Bar"/>. Методы с аргументами нуждаются в полном списке параметров.

вы не получите Intellisense для этого. И компилятор не будет жаловаться, если вы неправильно поняли синтаксис. Вам нужно будет проверить это с помощью документа генератор.

Я тестировал это с sandcastle, и он работает, но он слишком хрупкий, чтобы серьезно использовать его.

0