Комментарии к XML-документации с интерфейсами и реализующими классами [закрыты]

Question

Я документирую сборку, используя Комментарии к XML-документации, из которого chm файл будет создан с помощью Замок из песка.

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

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

Answer 1

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

С сайта ШФБ:

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

Второе обновление: в соответствии с этот рабочий элемент, «поддержка» Sandcastle для inheritdoc осуществляется с помощью инструмента SHFB.Суть в том, что я полагаю, что SHFB решит вашу проблему.

Answer 2

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

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

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

Как уже упоминалось, существует <inheritdoc> пометить в Замок из песка, но у него есть несколько недостатков по сравнению с FiXml:

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

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

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

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

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

• <inheritdoc />, <inherited /> Теги
• <see cref="..." copy="..." /> атрибут в <see/> бирка.

Вот его веб-страница и страница загрузки.

Answer 3

Такой инструмент, как ПризракДок может генерировать документацию по реализующим классам, когда вы используете сочетание клавиш.Это не совсем автоматически, но может помочь предотвратить слишком большое количество копий.

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

Answer 4

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

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