Комментарии к XML-документации с интерфейсами и реализующими классами [закрыты]
-
09-09-2019 - |
Вопрос
Я документирую сборку, используя Комментарии к XML-документации, из которого chm файл будет создан с помощью Замок из песка.
Моя сборка содержит различные интерфейсы, каждый из которых реализован одним классом (в моем сценарии это службы WCF).
Я добавил документацию к интерфейсам, есть ли у меня какой-нибудь способ автоматически документировать соответствующие методы в реализующих классах?
Решение
Кажется, в Sandcastle нет никакой поддержки такой автодокументации.А Конструктор файлов справки Sandcastle хотя реализует собственный тег inheritdoc.
С сайта ШФБ:
Поддержка включена дляu003Cinheritdoc /> тег, который позволяет вам наследовать документацию от базовых типов/участников.Это реализовано с помощью автономного инструмента, поэтому он также может использоваться другими сторонними инструментами и сценариями сборки.Этот инструмент предоставляет функции, помимо тех, которые можно найти в компоненте сборки, поставляемой с Sandcastle.
Второе обновление: в соответствии с этот рабочий элемент, «поддержка» Sandcastle для inheritdoc осуществляется с помощью инструмента SHFB.Суть в том, что я полагаю, что SHFB решит вашу проблему.
Другие советы
У меня есть ответ получше: 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/>
бирка.
Такой инструмент, как ПризракДок может генерировать документацию по реализующим классам, когда вы используете сочетание клавиш.Это не совсем автоматически, но может помочь предотвратить слишком большое количество копий.
Возможно, это можно автоматизировать с помощью скрипта.
AtomineerUtils автоматически сгенерирует для вас комментарии и подберет существующую документацию из перегрузок и переопределенного базового класса, избавляя вас от множества хлопот при дублировании информации там, где она необходима.