.NET xml docs - наследование документации
NDoc имеет XML-элемент наследство, который позволяет вам наследовать документацию члена от родительского класса (или реализованного интерфейса). Однако Visual Studio (то есть компилятор C#) не понимает этот тег и жалуется на отсутствие или полноту документации. Так же как и StyleCop и некоторые другие инструменты. Есть ли альтернативный подход? Как сделать так, чтобы документы оставались полными, но без дублирования XML-описаний?
Ответы 3
Одна альтернатива - использовать GhostDoc - надстройку для Visual Studio, которая автоматически генерирует комментарии для вас. Это, конечно, дублирует описание XML, которое является частью того, чего вы пытаетесь избежать, но, по крайней мере, он делает это автоматически за вас.
Что произойдет, если вы просто оставите документацию полностью для методов, которые наследуются или переопределяют методы интерфейса? Я подозреваю, что это зависит от того, как у вас настроен NDoc, но, конечно, в документации MSDN кажется, что это просто естественно наследует документы - и быстрая проверка предлагает, что VS не будет скучать, если вы не создаете документы для унаследованного метода. Конечно, стоит попробовать.
У меня есть ответ получше: 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> - его определенно лучше использовать, чем копировать XML-комментарии, но у него мало недостатков по сравнению с FiXml:
- Sandcastle создает скомпилированные файлы справки в формате HTML - он не изменяет файлы
.xml. содержащий извлеченные комментарии XML. Но эти файлы используются многими инструментами, включая .NET Reflector и браузер классов \ IntelliSense в Visual Studio .NET. Поэтому, если вы используете только Sandcastle, вы не увидите там унаследованной документации. - Реализация Sandcastle менее эффективна. Например. нет
<see ... copy = "true" />.
Подробнее см. Описание Sandcastle <inheritdoc>.
Теоретически неплохо (+1 за ссылку), но на практике я обнаружил, что FiXml слишком глючит, чтобы быть практичным. Иногда это приводит к блокировке файла, и мне придется перезапускать VS, чтобы построить снова. Я заметил, что он загружает все ссылочные сборки в текущий AppDomain, а не создает отдельный AppDomain, который он может позже выгрузить. Может быть, поэтому.
FiXml теперь официально не поддерживается, и в VS2013 он не работает, особенно в x64. Немного поигравшись со сценариями сборки, он запустится, но на самом деле он не будет работать должным образом и не сможет запускаться дважды. См. Этот вопрос на SO-lookalike справочном сайте Xtensive для получения дополнительной информации: support.x-tensive.com/question/5419/problem-with-fixml
Я создал инструмент командной строки для последующей обработки файлов XML-документации, чтобы добавить поддержку тега <inheritdoc />.
Это не помогает с Intellisense в исходном коде, но позволяет включать измененные файлы XML-документации в пакет NuGet и, следовательно, работает с Intellisense в указанных пакетах NuGet.
Подробнее см. www.inheritdoc.io (доступна бесплатная версия).
Спасибо за ответ. Если вы оставите комментарии, NDoc правильно наследует документы, но VS по-прежнему жалуется на отсутствие комментариев к документам, что немного раздражает. GhostDoc - хороший инструмент. У ReSharper также есть связанная функция - копирование комментариев из базы.