Комментарии к документации XML с интерфейсами и классами реализации

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

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

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


.net documentation chm xml-documentation
person Richard Ev    schedule 15.04.2009    source источник

Ответы (4)


arrow_upward
1
arrow_downward

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

С сайта SHFB:

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

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

person Peter Lillevold    schedule 15.04.2009

arrow_upward
3
arrow_downward

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

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

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

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

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

Дополнительные сведения см. В <inheritdoc> описании Sandcastle.

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

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

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

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

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

person Alex Yakunin    schedule 03.07.2009

arrow_upward
1
arrow_downward

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

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

person driis    schedule 15.04.2009
comment
Может ли GhostDoc изменить эталонный XML-файл или он изменяет фактический код? Если первое верно, это можно было бы использовать вместе с Sandcastle ... - person Peter Lillevold; 15.04.2009

arrow_upward
1
arrow_downward

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

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

person Jason Williams    schedule 28.04.2009