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

Вы можете сделать это довольно легко с помощью тега 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)
{
    //
}

Вот справочная страница из справки Sandcastle Графический интерфейс File Builder, полностью описывающий его использование.

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

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

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

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

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

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

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

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

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

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

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

Изменить:

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

Попробуйте GhostDoc! Меня устраивает :-)

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

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

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

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

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

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

Дополнительные сведения см. В <inheritdoc> описании Sandcastle.

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

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

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

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

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

/// <inheritDoc/>

Прочтите здесь

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

Я создал библиотеку для пост-обработки файлов XML-документации, чтобы добавить поддержку тега ‹inheritdoc /›.

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

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

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

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