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

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

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

спасибо.

9 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)
{
    //
}

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

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

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

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

4

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

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

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

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

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

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

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

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

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

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

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

2
/// <inheritDoc/>

читать здесь

использовать

1

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

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

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

1

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

0

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

-1