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

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

ОБНОВИТЬ:

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

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

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

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

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

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

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

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

Благодарю.

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

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

Ниже приведена страница справки из GUI проекта Sandcaple Help File Builder, которая описывает его использование в полном объеме.

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

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

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

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

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

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

Перейдите в Настройки -> Настройки клавиатуры и назначьте ключ GhostDoc.AddIn.RebuildDocumentation (я использовал Ctrl-Shift-Alt-D ). alt text http://sofru.miximages.com/c%23/10dd1f9.png

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

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

 ///  /// Implements  ///  ///  

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

Редактировать:

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

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

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

У меня есть лучший ответ: FiXml .

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

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

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

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

Подробнее см. Описание Sandcastle .

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

  • Нет поддержки для наследования документации из базового classа или интерфейса. Т.е. документация для любого переопределенного элемента должна быть написана с нуля, хотя обычно довольно желательно наследовать, по крайней мере, ее часть.
  • Нет поддержки для вставки обычно используемых шаблонов документации , таких как «Этот тип singleton – используйте свойство чтобы получить единственный экземпляр этого .” Или даже “Инициализирует новый экземпляр class. ”

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

  • ,
  • атрибут в .

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

 ///  

Читать здесь

Использовать это

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

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

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

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

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

Давайте будем гением компьютера.