.NET XML документы - наследование документации
В 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> тег в Sandcastle - его определенно лучше использовать, чем копировать комментарии XML, но он имеет несколько недостатков по сравнению с FiXml:
- Sandcastle создает скомпилированные файлы справки HTML - он не изменяется
.xmlфайлы, содержащие извлеченные комментарии XML. Но эти файлы используются многими инструментами, включая.NET Reflector и браузер классов \ IntelliSense в Visual Studio .NET. Поэтому, если вы используете только Sandcastle, вы не увидите там унаследованной документации. - Реализация Sandcastle менее мощная. Например, нет
<see ... copy="true" />,
Посмотреть Сандкасл <inheritdoc> описание для дальнейших деталей.
Я создал инструмент командной строки для пост-обработки файлов документации XML, чтобы добавить поддержку тега
Он не помогает с Intellisense в исходном коде, но он позволяет включать измененные файлы документации XML в пакет NuGet и поэтому работает с Intellisense в ссылочных пакетах NuGet.
См. https://www.inheritdoc.io/ для деталей (бесплатная версия доступна).