Документы .NET xml — наследование документации

Question

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

Answer 1

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

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

Answer 2

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

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

• Когда исходный комментарий изменяется (что часто происходит во время разработки), его клон не является.
• Вы производите огромное количество дубликатов.Если вы используете какие -либо инструменты анализа исходного кода (например,Дублируйте 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" />.

Видеть Песчаный замок <inheritdoc> описание для получения более подробной информации.

Answer 3

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

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

Подробности смотрите в www.inheritdoc.io .