.NET XML документы - наследование документации - PullRequest
Новая
       21

.NET XML документы - наследование документации

36 голосов
/ 22 ноября 2008

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

Ответы [ 3 ]

22 голосов
/ 03 июля 2009

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

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

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

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

  • Нет поддержки наследования документации от базового класса или интерфейса. Т.е. документация для любого переопределенного члена должна быть написана с нуля, хотя обычно очень желательно наследовать хотя бы ее часть.
  • Нет поддержки для вставки часто используемых шаблонов документации , таких как «Этот тип является одиночным - используйте его свойство <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> .

14 голосов
/ 22 ноября 2008

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

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

1 голос
/ 21 декабря 2017

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

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

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

...