Способы синхронизации комментариев интерфейса и реализации в 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 Castle, но он не работает в intellisense подсказки.

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

спасибо.

82
c# documentation xml-documentation

9 ответов

вы можете сделать это довольно легко, используя 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)
{
    //
}

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

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

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

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

54

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

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

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

перейти к Параметры -> Клавиатура настройки и назначить клавишу GhostDoc.AddIn.RebuildDocumentation (я использовал Ctrl-Shift-Alt-D). alt текст http://i44.tinypic.com/10dd1f9.png

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

11

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

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

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

Edit:

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

5

попробовать GhostDoc! Это работает для меня :-)

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

4

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

клонирование, безусловно, работает, но имеет существенные недостатки, например:

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

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

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

посмотреть Сандкасл-х <inheritdoc> описание для получения дополнительной информации.

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

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

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

  • <inheritdoc />, <inherited /> теги
  • на <see/> тег.

здесь его веб-страницы и страница скачать.

2
1

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

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

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

1

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

0

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

-1