Использование XML-тегов

В Delphi, так сказать, "из коробки",доступно создание документации на основе XML. Смысл такого документирования заключается в следующем: над элементами кода, которые необходимо отразить в документации (класс, метод, переменная и т.д.) помещается специальный блок, каждая строка которого начинается с тройного слэша (///). В этом блоке располагаются XML-теги, содержащие какую-либо информацию по элементу (описание, значения переменных, ссылки на другие разделы документации и т.д.). Например, так можно сделать небольшой описание для класса формы:

На текущий момент, в Delphi XE2 используются следующие XML-теги для формирования документации:

· summary – краткое описание функции или класса;

· para– тег, используемый для задания нового параграфа;

· c– используется для задания создания моноширинного текста;

· code–преформатированный текст, например, исходный код;

· remarks– замечания к функции или классу;

· paramname="ParameterName"– описание параметра с названием ParameterName;

· see– дополнительные источники информации по элементу кода;

· returns– описание возвращаемых значений;

· exceptioncref="EExceptionTypeName"– исключения, которые могут быть сгенерированы в результате работы метода;

· permissioncref="PermissionType"–разрешенияметода.

Используя приведенные выше XML-теги, можно создать, к примеру, такое описание для функции:

Что мы получаем в итоге от использования такого вида документирования? Во-первых, в Delphi есть такой полезный инструмент как HelpInsight, который находит всю XML-документацию в коде и формирует на её основе вот такие удобные подсказки:

Собственно, использование для HelpInsight XML-документации исходного кода должно вполне хватить для нормальной работы с проектом. Ну, а если не хватит HelpInsight, то тогда, во-вторых, на основе XML-документации можно генерировать HTML-справку по коду.Для этого используется инструмент моделирования ModelView.

Примечание.Конечно, использовать инструмент моделирования исключительно для того, чтобы сгенерировать HTML-справку – это крайне нерационально, т.к. этот инструмент имеет на порядок больше полезных функций, но его использование являетсянаиболее простым способом создания документации.