.NET xml docs - наследующая документация

NDoc имеет элемент XML inheritdoc, который позволяет наследовать документацию члена из родительского класса (или реализованного интерфейса). Однако Visual Studio (т.е. Компилятор С#) не понимает этот тег и жалуется на то, что документация не присутствует или не завершена. Также есть StyleCop и некоторые другие инструменты. Есть ли альтернативный подход? Как вы продолжаете хранить документы полностью, но не дублируя описания XML?

ОТВЕТЫ

Ответ 1

Один из вариантов заключается в использовании GhostDoc - надстройки для Visual Studio, которая автоматически генерирует для вас комментарии. Это, конечно, дублирует XML-описание, которое является частью того, что вы пытаетесь избежать, но по крайней мере оно делает это автоматически для вас.

Что произойдет, если вы просто оставите документы полностью для методов, которые наследуются, или переопределяют методы интерфейса? Я подозреваю, что это зависит от того, как вы настроили NDoc, но, разумеется, в документации MSDN, естественно, наследуется документация. И быстрая проверка предполагает, что VS не будет взлетать, когда вы не будете вводить документы для унаследованного метода. Стоит попробовать, конечно.

Ответ 2

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

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

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

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

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

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

  • <inheritdoc />, <inherited /> теги
  • <see cref="..." copy="..." /> в теге <see/>.

Вот его веб-страница и страница загрузки (неработающие ссылки).

Наконец, есть тег <inheritdoc> в Sandcastle - это определенно лучше использовать его, чем копировать комментарии XML, но у него мало недостатки по сравнению с FiXml:

  • Sandcastle создает скомпилированные файлы справки HTML - он не изменяет файлы .xml содержащий извлеченные комментарии XML. Но эти файлы используются многими инструментами, включая .NET Reflector и браузер класса \IntelliSense в Visual Studio.NET. Поэтому, если вы используете только Sandcastle, вы не увидите там унаследованной документации.
  • Реализация Sandcastle менее эффективна. Например. нет <see ... copy="true" />.

Подробнее см. описание Sandcastle <inheritdoc>.

Ответ 3

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

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

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