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

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

6 голосов
/ 14 мая 2011

Код: 

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

Ответы [ 2 ]

1 голос
/ 14 мая 2011

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

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

0 голосов
/ 25 июля 2018

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

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

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

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

...