5.1 Введение

На верх  Назад  Вперёд

Файл описания (description) представляет собой XML-документ, что означает, что он является своего рода форматом HTML или SGML, однако он более структурирован, чем HTML, что упрощает анализ - и упрощает его подключение или объединение с исходным файлом Pascal. Поскольку разрешенный синтаксис использует много HTML-тегов, это упрощает кодирование для тех, кто знаком с написанием HTML.

Более подробную информацию о формате XML, SGML и HTML можно найти на веб-сайте консорциума W3 (World Wide Web): http://www.w3.org/

Остальная часть этой главы предполагает базовое знание тегов, их атрибутов и разметки язык, так что эти термины не будут объяснены здесь.

Минимальный файл документации будет выглядеть примерно так:

<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-description>
<package name="fpc">
<module name="Classes">
</module>
</package>
</fpdoc-description>

Тег заголовка xml является обязательным и указывает, что файл содержит документ XML документации.

Внутри документа может появиться один или несколько тегов описания верхнего уровня fpdoc.

Внутри документа может появиться один или несколько тегов fpdoc-descriptions верхнего уровня. Каждый из этих тегов может содержать один или несколько тегов package, которые должны иметь атрибут name. Атрибут name будет использоваться fpdoc для выбора узлов документации.

Внутри тега package может появиться один или несколько тегов module. В модуле должен быть один тег module, который и будет помещён в документацию. Значение атрибута name нечувствительно к регистру, т.е.

<module name="CRT">

может использоваться для документации модуля crt.

Как указано выше, описание документации мало что делает. Чтобы написать реальную документацию, тег module должен что-то содержать для каждого идентификатора, который встречается в интерфейсном разделе модуля.

Для каждого идентификатора в заголовке интерфейса модуля он должен содержать тег module, который документирует его: это тег element. Атрибут name тега элемента связывает описание с идентификатором: атрибут name должен содержать полное имя идентификатора в модуле.

Например, для документирования типа

Type

 MyEnum = (meOne,meTwo,meThree);

должен существовать тег element для myenum:

<element name="myenum">
</element>

Но также для каждого из трех перечисленных значений должен существовать тег element:

<element name="myenum.meOne">
</element>
<element name="myenum.meTwo">
</element>
<element name="myenum.meThree">
</element>

Как видно, имена идентификаторов следуют иерархической структуре. Подробнее об этом в следующем разделе.

Теперь теги для типов присутствуют, все, что нужно сделать, это заполнить его фактическим описанием. Для этого в тег element можно поместить несколько тегов. Наиболее важным тегом является тег descr. Содержимое тега descr будет использоваться для описания типа, функции, константы или переменной:

<element name="myenum">
<descr>
Тип MyEnum - простой тип перечисления, который используется
исключительно демонстрационных целей.
</descr>
</element>

Второй важный тег - это тег short. Он должен содержать краткое описание идентификатора, предпочтительно описание, которое укладывается в одну строку. Тег short будет использоваться в различных обзорах, в верхней части страницы в документации HTML (резюме), или будет использоваться вместо тега descr, если последний недоступен. Его также можно использовать в разных других случаях: например, различные значения типа перечисления будут выложены в таблице, используя short (краткое) описание:

<element name="myenum.meOne">
<short>Первое значение перечисления</short>
</element>
<element name="myenum.meTwo">
<short>Второе значение перечисления</short>
</element>
<element name="myenum.meThree">
<short>Третье значение перечисления</short>
</element>

Это будет преобразовано в таблицу, выглядящую примерно так:

meOne        Первое значение перечисления

meTwo        Второе значение перечисления

meThree        Третье значение перечисления

Список ошибок функций и процедур может быть описан внутри тега errors. Этот тег эквивалентен тегу descr, но помещается под заголовком Ошибки в создаваемой документации.

Наконец, для перекрестных ссылок между связанными функциями, типами или классами также вводится тэг seealso. Он будет использоваться для выкладки серии ссылок на соответствующую информацию. Этот тег может содержать только субтеги, которые являются тегами link . Подробнее о теге link см. link (186).

Если определенный идентификатор появился только в определенной версии библиотеки, эта информация может быть указана в теге version, см. version (233) для дополнительной информации.

Следующий пример иллюстрирует использование:

<element name="myenum">
<descr>

Тип MyEnum - простой тип перечисления, который используется

исключительно демонстрационных целей.

</descr>
<version>Тип myenum появился в версии 2.1</version>
</element>

При документировании методов или свойств можно позволить движку fpdoc ссылаться на родительский метод, когда он генерирует обзор методов или свойств. Есть два способа достижения этого:

1.Не включать тег element

2.Укажите атрибут link с именем родительского метода, который содержит документацию, как в следующем примере:

<element name="TParent.SomeMethod">
</element>
<element name="TChild.SomeMethod" link="TParent.SomeMethod"/>

это можно использовать для ускорения поиска родительской реализации или для пропуска нескольких родительских классов.

Чтобы добавить раздел или страницу документации, которая напрямую не связана с одним идентификатором в модуле, можно использовать тег topic. Этот тег может отображаться внутри тега package или module и может содержать тэги short или descr. Содержимое тега short будет использоваться для названия раздела или страницы. В онлайновых форматах на странице пакета или модуля появится краткий список тем связанных со ссылками на страницы, содержащие текст тем. В линейном формате  перед описанием всех идентификаторов будут вставлены эти разделы.

Если тема появляется в теге package, то она может быть вложенной: могут использоваться 2 уровня тем. Для тем внутри модуля это не так: они не могут быть вложенными (уровень вложенности в формате линейной документации ограничен).

Ниже приведен пример допустимого тега темы:

<module name="CRT">
<topic name="UsingKeyboard">
<short>Использование функций клавиатуры</short>
<descr>
Для использования функций клавиатуры модуля CRT надо: во первых ...
</descr>
</topic>

Узлы темы могут быть полезны для добавления поясняющих разделов ’how to’ в модуль или для предоставления общей справки по IDE.