3.1 fpdoc

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

Использование FPDoc довольно просто. Он требует некоторых параметров командной строки и на основе этих параметров создает документацию. Параметры командной строки могут задаваться как длинными или короткими параметрами, как это обычно бывает для большинства программ GNU.

В принципе, требуется только две опции командной строки:

package (пакет)

Указывает имя пакета, для которого должна быть создана документация. Можно указать только один вариант пакета.

input (вход)

Имя файла модуля, для которого должна быть создана документация. Это может быть просто имя файла, но можно использовать и некоторые параметры синтаксиса, которые могут быть предоставлены сканеру Free Pascal. Может быть использовано более одного параметра input (ввода), и документация будет сгенерирована для всех указанных входных файлов.

Некоторые примеры:

fpdoc --package=fcl --input=crt.pp

Таким образом сканируется файл crt.pp и генерируется документация для него в каталоге с именем fcl.

fpdoc --package=fcl --input=’-I../inc -S2 -DDebug classes.pp’

Таким образом сканируется файл classes.pp с определенным (в fpc) символом DEBUG , сканер будет искать включенные файлы в каталоге ../inc, и будет принят синтаксис OBJFPC -режим (OBJFPC-mode).

(дополнительную информацию об этих параметрах см. в руководстве пользователя компилятора Free Pascal)

С помощью приведенных выше команд в формате HTML будет создан набор файлов документации (это стандарт). Не будет описания каких-либо идентификаторов, найденных в интерфейсном разделе модуля, но в документации будут присутствовать все объявления идентификаторов.

Фактическая документация (т.е. описание каждого из идентификаторов) находится в файле описания, он может быть указан с помощью параметра descr:

fpdoc --package=fcl --descr=crt.xml --input=crt.pp

Таким образом сканируется файл crt.pp и создается для него документация, при этом используются описания, найденные в файле filecrt.xml. Документация будет создана в каталоге с именем fcl.

fpdoc --package=fcl --descr=classes.xml \
     --input=’-I../inc -S2 -DDebug classes.pp’

Все опции должны быть указаны в одной строке. Таким образом сканируется файл classes.pp с символом DEBUG, сканер будет искать включенные файлы в каталоге ../inc, и будет принят синтаксис OBJFPC -режима.

Можно указать более одного входного файла или файла описания:

fpdoc --package=fcl --descr=classes.xml --descr=process.xml \
     --input=’-I../inc -S2 -DDebug classes.pp’ \
     --input=’-I../inc -S2 -DDebug process.pp’

Здесь будет создаваться документация для двух модулей: classes и process

Формат файла описания обсуждается в следующей главе.

Могут быть созданы другие форматы, такие как latex:

fpdoc --format=latex --package=fcl \
     --descr=classes.xml --descr=process.xml\
     --input=’-I../inc -S2 -DDebug classes.pp’ \
     --input=’-I../inc -S2 -DDebug process.pp’

Таким образом создается файл LaTeX с именем fcl.tex , который содержит документацию по модулям classes и process. Файл latex не содержит преамбулы документа, он начинается с команды главы. Он должен быть включен (с использованием команды LaTeX include) в латексном документе с преамбулой.

Выход FPDoc можно дополнительно настроить несколькими параметрами командной строки, которые будут объяснены в следующем разделе.