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

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

ОБНОВИТЬ:

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

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, но он не работает в IntelliSense всплывающих подсказках.

Пожалуйста, поделитесь своими идеями.

Спасибо.

Вы можете сделать это довольно легко с помощью inheritdocтега Microsoft Sandcastle (или NDoc) . Он официально не поддерживается спецификацией, но настраиваемые теги вполне приемлемы, и действительно, 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 Help 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/>, я одобряю сообщение Noldorin. Это гораздо лучшее решение. Тем не менее, я все же рекомендую GhostDoc в целом.

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

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

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

Как уже упоминалось, <inheritdoc>в Sandcastle есть тег , но он имеет несколько недостатков по сравнению с 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 вы можете скопировать его, но я не думаю, что он все время синхронизирован.