Документация XML-комментариев с интерфейсами и реализующими классами

Question

Я документирую сборку с использованием XML Documentation Comments, из которой будет создан файл chm с использованием Sandcastle.

Моя сборка содержит различные интерфейсы, каждый из которых реализуется одним классом (в моем сценарии это службы WCF).

Я добавил документацию на интерфейсы, есть ли способ автоматически документировать соответствующие методы для классов реализации?

Answer 1

Кажется, нет никакой поддержки для такой автодокументации в Sandcastle. Sandcastle Help File Builder реализует собственный тег inheritdoc.

С сайтом SHFB:

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

Второе обновление: согласно this workitem, то "поддержка" Sandcastle для inheritdoc через инструмент SHFB. Полагаю, что SHFB решает вашу проблему.

Answer 2

Инструмент, такой как GhostDoc, может генерировать документацию по классам реализации при использовании сочетания клавиш. Это не является полностью автоматическим, но может помочь предотвратить слишком много скопирования.

Возможно, это может быть автоматизировано с помощью скрипта.

Answer 3

AtomineerUtils будет автоматически генерировать комментарии для вас, и он подбирает существующую документацию из перегрузок и переопределенного базового класса, что избавляет вас от лишних хлопот при дублировании информации там, где это необходимо.

http://www.atomineer.com/AtomineerUtils.html

Answer 4

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

Клонирование комментарии с GhostDoc \ AtomineerUtils, конечно, работает подход, но он имеет существенные недостатки, например .:

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

Как уже было сказано, есть <inheritdoc> тег в Sandcastle, но он имеет ряд недостатков по сравнению с FIXML:

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

Для получения дополнительной информации см. Sandcastle's <inheritdoc> description.

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

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

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

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

Адрес its web page и download page.