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


98

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

ОБНОВИТЬ:

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

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 всплывающих подсказках.

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

Спасибо.


Реализована ли эта функция? visualstudio.uservoice.com/forums/121579-visual-studio/…
hellboy

Как я могу сделать так, чтобы Atomineer Pro позволял генерировать тег документации <inheritDoc /> для реализации, если документация для интерфейса доступна?
hellboy

3
Вы правы, <inheritdoc/>в Visual Studio не работает. Пожалуйста, проголосуйте за отчет об ошибке на visualstudio.uservoice.com/forums/121579-visual-studio/…
полковник Паник

Ответы:


62

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


Эй, как мило! Мне нравится Sandcastle!
Тор Хауген

Сообщение отредактировано, чтобы ответить на обновленный вопрос.
Нолдорин

2
можно ли это сделать на уровне класса? так что мне не нужно помещать /// <inheritdoc /> перед каждым методом.
Энтони Скотт

1
Я заметил одну вещь: <inheritdoc/> она не наследует документацию по <param>тегу.
Стивен

1
Поднимитесь и проголосуйте за эту функцию голосового управления, чтобы <inheritdoc /> было официально добавлено в спецификацию C # и работало с VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/…
deadlydog

14

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

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

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

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

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


Самая новая версия (5.3.16270) GhostDoc также может создавать унаследованные документы. Я просто попробовал это для своих реализаций интерфейса. Приятный бонус, он также добавляет исключения с сообщением о брошенном исключении :-)
Christoph

6

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

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

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

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

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


4

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

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


6
Лично мне не нравится GhostDoc. Он генерирует документацию там, где ее фактически нет. Это скрывает тот факт, что что-то не задокументировано. Просто личное мнение, я не говорю, что это вообще что-то плохое.
Стефан Штайнеггер

1
Согласитесь с комментарием Стефана в том, что GhostDoc не идеален, однако он автоматически извлекает такие «унаследованные» комментарии, так что это довольно хороший ответ на вопрос.
Стив

Стефан, я не согласен - наоборот, поскольку GhostDoc отражает только документацию, которую вы уже «вложили» в имена своих членов (путем построения прозы из имен), он генерирует документацию только там, где документация уже существует (неявно). По сути, он ничего не «производит», но сгенерированная проза - отличная отправная точка, к которой вы можете добавить реальную ценность. Настоящая документация все еще требует некоторой работы.
Тор Хауген

2

У меня есть ответ получше: 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/>теге.

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



1

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

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

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


0

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


3
Я бы не использовал здесь интерфейс, если бы не подделывал его в тестах.
Валентин Васильев

0

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

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.