Способы синхронизации комментариев интерфейса и реализации в С#

Существуют ли автоматические способы синхронизации комментариев между интерфейсом и его реализацией? В настоящее время я документирую их оба и не хотел бы вручную синхронизировать их.

UPDATE:

Рассмотрим этот код:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Когда я создаю класс следующим образом:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Здесь комментарии не отображаются:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

Тег <inheritDoc/> отлично сгенерирует документацию в Sand Castle, но он не работает в подсказках intellisense.

Поделитесь своими идеями.

Спасибо.

Ответ 1

Вы можете сделать это довольно легко, используя тег Microsoft Sandcastle (или NDoc) inheritdoc. Он официально не поддерживается спецификацией, но пользовательские теги являются совершенно приемлемыми, и действительно Microsoft решила скопировать этот (и один или два других тега) из NDoc, когда они создали Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Здесь - справочная страница из графического интерфейса Builder Builder Sandcastle, в котором подробно описывается его использование.

(Конечно, это не специально "синхронизация", как упоминается в вашем вопросе, но, похоже, это именно то, что вы ищете.)

В качестве примечания это звучит как совершенно справедливая идея для меня, хотя я заметил, что некоторые люди думают, что вы всегда должны реагировать на комментарии в производных и реализованных классах. (Я сам это сделал, документирую одну из своих библиотек, и я не вижу никаких проблем вообще.) Почти всегда нет причин для того, чтобы комментарии вообще отличались, так почему бы просто не наследовать и сделать это простым способом?

Изменить: Что касается вашего обновления, Sandcastle также может позаботиться об этом для вас. Sandcastle может выводить модифицированную версию фактического XML файла, который он использует для ввода, что означает, что вы можете распространять эту модифицированную версию вместе с библиотечной DLL вместо той, что была построена непосредственно Visual Studio, что означает, что у вас есть комментарии в intellisense, а также файл документации (CHM, что угодно).

Ответ 2

Если вы его еще не используете, я настоятельно рекомендую бесплатное дополнение Visual Studio под названием GhostDoc. Это облегчает процесс документации. Посмотрите мой комментарий на несколько связанный вопрос.

Хотя GhostDoc не будет выполнять синхронизацию автоматически, он может помочь вам в следующем сценарии:

У вас есть документированный метод интерфейса. Реализуйте этот интерфейс в классе, нажмите сочетание клавиш GhostDoc, Ctrl-Shift-D, и комментарий XML из интерфейса будет добавлен к реализованному методу.

Перейдите в настройки Параметры → Клавиатура и назначьте клавишу для GhostDoc.AddIn.RebuildDocumentation (я использовал Ctrl-Shift-Alt-D).

Теперь, если вы измените XML-комментарий к интерфейсу, просто нажмите эту клавишу быстрого вызова на реализованном методе, и документация будет обновлена. К сожалению, это не работает наоборот.

Ответ 3

Обычно я пишу такие комментарии:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Методы используются только интерфейсом, поэтому этот комментарий даже не отображается во всплывающих подсказках при кодировании.

Edit:

Если вы хотите видеть документы, когда вы вызываете класс напрямую и не используете интерфейс, вам нужно записать его дважды или использовать инструмент, например GhostDoc.

Ответ 4

Попробуйте GhostDoc! Это работает для меня: -)

Изменить: Теперь, когда мне сообщили о поддержке Sandcastle для <inheritdoc/>, я поддерживаю пост Noldorin. Это гораздо лучшее решение. Тем не менее, я по-прежнему рекомендую GhostDoc на общей основе.

Ответ 5

У меня есть лучший ответ: FiXml. Я один из его авторов

Клонирование - это, безусловно, рабочий подход, но он имеет существенные недостатки, например:

Когда исходный комментарий изменяется (что часто происходит во время разработки), его клона нет.
Вы производите огромное количество дубликатов. Если вы используете какой-либо инструменты анализа исходного кода (например, Duplicate Finder в Team City), он будет найти в основном ваши комментарии.

Как уже упоминалось, в Sandcastle есть тег <inheritdoc>, но он имеет несколько недостатков по сравнению с FiXml:

Sandcastle создает скомпилированные файлы справки HTML - обычно он не изменяется .xml файлы, содержащие извлеченные комментарии XML (наконец, это невозможно сделать "на лету" во время компиляции).
Реализация Sandcastle менее мощная. Например. нет <see ... copy="true" />.

Подробности смотрите в Сандкасле <inheritdoc>.

Краткое описание FiXml: это постпроцессор XML-документации, созданной С#\Visual Basic.Net. Он реализован как задача MSBuild, поэтому его довольно легко интегрировать в любой проект. В нем рассматриваются несколько досадных случаев, связанных с написанием XML-документации на следующих языках:

Не поддерживается наследование документации от базового класса или интерфейса. Т.е. документация для любого переопределенного члена должна быть написана с нуля, хотя обычно очень желательно наследовать хотя бы ее часть.
Отсутствует поддержка для вставки часто используемых шаблонов документации, таких как "Этот тип одноэлементный - используйте его свойство <see cref="Instance" />, чтобы получить единственный его экземпляр.", Или даже "Инициализирует новый экземпляр класса <CurrentType>". "

Для решения указанных проблем предусмотрены следующие дополнительные теги XML:

Теги <inheritdoc />, <inherited />
<see cref="..." copy="..." /> атрибут в теге <see/>.

Вот его веб-страница и страница загрузки.

Ответ 6

/// <inheritDoc/>

Читайте здесь

Используйте это

Ответ 7

Я построил библиотеку для последующей обработки файлов документации XML, чтобы добавить поддержку < inheritdoc/ > тег.

Хотя он не помогает с Intellisense в исходном коде, он позволяет добавлять файлы XML-документации, модифицированные XML, в пакет NuGet и, следовательно, работает с Intellisense в упомянутых пакетах NuGet.

Дополнительная информация на www.inheritdoc.io (доступна бесплатная версия).

Ответ 8

Не делай этого. Подумайте об этом так: если оба комментария должны быть одинаковыми все время, то один из них не нужен. Должна быть причина для комментария (помимо какой-то странной обязанности комментировать блокировать каждую функцию и переменную), поэтому вам нужно выяснить, что это за уникальная причина, и документировать это.

Ответ 9

С ReSharper вы можете скопировать его, но я не думаю, что он синхронизирован все время.