Автодокументация исходников посредством PasDoc

Настоящая статья представляет собой описание основных возможностей утилиты PasDoc. Статья не претендует на полноту, но вполне может использоваться для начального знакомства с программой. Для настоящего освоения PasDoc лучше всего просто взять и поэкспериментировать, вооружившись оригинальной (на английском) Wiki-документацией с официального сайта: http://pasdoc.sourceforge.net/.

PDF-версия для печати (202KB)

Содержание

• Общие сведения
  • Статус
  • Принцип работы
  • Источники информации
• Синтаксис комментариев
  • Блоки
  • PasDoc-теги
    • Теги-описания
    • Гиперссылки
    • Форматирование
    • Специальные
• Расширенные возможности
  • Директивы компилятора
    • Условные директивы
    • {$INCLUDE ...}
  • Внешние файлы
    • Описания
    • HTML-шапка и подвал
    • «Введение» и «Заключение»
  • Прочие вкусности
    • Поиск
    • GraphViz
    • Проверка орфографии
• Синтаксис командной строки
  • Ключи
• Заключение

Общие сведения

Программа PasDoc предназначена для того, чтобы формировать документацию по модулям Pascal, используя комментарии в исходных текстах. Поддерживается синтаксис как Delphi, так и Free Pascal¹. Сама программа также может быть скомпилирована как тем, так и другим. Впрочем, экспериментальная оболочка GUI должна собираться в Lazarus'е — форм в борландовском формате в исходниках не замечено.

Соответственно, PasDoc может работать на разных платформах — тех, которые поддерживаются FPC (а нас, собственно, они и интересуют).

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

Статус

Текущая версия, использованная при написании данной статьи — 0.10.0. В последнее время проект довольно активно развивается, свежую версию см. на SourceForge.

Лицензия — GNU GPLv2.

Сайт — http://pasdoc.sipsolutions.net/ или http://pasdoc.sourceforge.net/.

Принцип работы

PasDoc обрабатывает исходные тексты модулей, выполняя синтаксический разбор — в результате формируется общая структура документации, и разбирая текст комментариев — из них формируются описания программных элементов. При этом могут разбираться как все комментарии, так и только помеченные специальными маркерами (например, “**”), что зачастую удобнее.

Описанием элемента считается непосредственно предшествующий ему комментарий, или непосредственно следующий за ним и начинающийся с символа “<”. Исключение может быть сделано для полей, свойств и т.д., которые удобнее описывать в комментарии родительского элемента (записи, класса…) используя специальный pasdoc-тег “@member”; для значений типа-перечисления — “@value”; а также для параметров подпрограмм — “@param”.

Специальные pasdoc-теги используются также для указания специальной информации (автор, краткое описание…), гиперссылок на другие программные элементы и т.д. Далее мы рассмотрим их подробнее.

Источники информации

Бинарный дистрибутив PasDoc документации не содержит (вероятно, она появится к релизу). Тем не менее, в архиве с исходниками присутствует руководство по программе в форматах HTML и PDF. Впрочем, содержание данного руководства несколько отстает от текущих возможностей программы, как это часто бывает в открытых проектах. Наиболее полную и свежую информацию можно получить на сайте PasDoc.

Синтаксис комментариев

Блоки

Рассмотрим, как PasDoc разбирает комментарии в программе… А разбирает он их поблочно. Блок в данном случае — единичный блочный комментарий — “{ ... }” или “(* ... *)”, или же последовательность строчных комментариев — “//”, между которыми нет значащих символов — допустимы переводы строки с пробелами. Если перед элементом расположены два блока комментария, то используется только последний.

Зачастую не все комментарии желательно вносить в описания — могут понадобиться комментарии и сугубо технические. PasDoc предлагает использовать механизм маркеров — специальных последовательностей символов, которые выделяют «документирующие» комментарии и позволяют игнорировать прочие. Подробнее см. далее описание параметров командной строки “--staronly” и “--marker”. При использовании маркеров ими следует помечать комментарии, которые должны рассматриваться как описания — вставлять маркер сразу после открывающих символов комментария. Например, если в качестве маркера выбрана последовательность “**” (именно это делает параметр “--staronly”), то в описания попадут только комментарии вида: “{** ... }”, “(*** ... *)” и “//** ...”.

Блок с описанием может располагаться и сразу после объявления идентификатора, но в этом случае следует непосредственно за открывающими символами комментария (и маркером, если таковые используются) поместить символ “<” (знак «меньше»). Следует отметить, что в этом случае строчные комментарии, идущие подряд, блоком уже не считаются.

Пример

unit Dummy;

{< Дурацкий модуль.

 Специально для примера — второй абзац описания.
}

interface

type
  (* Совершенно дурацкий тип-запись. *)
  TDummy = record
           A : Integer; //< Поле «A»
           B : Boolean; //< поле «B»
           end;

implementation

end.

В примере для простоты не использованы маркеры.

Особо следует отметить пустую строчку в первом комментарии. Таким образом в описании разделяются абзацы (в случае выходного формата HTML — тег “

...

PasDoc-теги

Теперь о самом «вкусном»: PasDoc использует специальные ключевые слова, именуемые «тегами», для дополнительной разметки внутри комментариев-описаний. Все теги начинаются с символа “@” («собака»), а чтобы поместить сам этот символ в выводимый текст, его следует удвоить — “@@”.

Теги могут иметь параметры, заключаемые в круглые скобки. Как правило, параметр единственный и представляет собой некий текст, трактуемый так же, как и общий текст описания. В некоторых случаях параметр трактуется специальным образом: теги “@link”, “@code”, “@longcode”, “@html” и “@latex”. Кроме того, ряд тегов трактует первое слово как идентификатор, а последующий текст — как описание.

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

Теги-описания

@abstract(описание)

Краткое описание используется в разного рода списках, например, на странице «Все модули» или «Все идентификаторы». В то же время, данное описание попадает и в основное описание элемента — первой строкой.

См. также ключ “--auto-abstract”.

@author(имя <e-mail>)

В основном используется внутри описания модуля, но может применяться и для классов, интерфейсов и object-типов. Очевидным образом содержит информацию об авторе. Например:

@author(Вася Пупкин )

@created(дата создания) и @lastmod(дата изменения)

Позволяют указать дату создания и последнего изменения документа. Применяются только в тех же случаях, что и “@author”. Какой-либо специальный формат даты соблюдать не требуется.

@cvs(строка cvs)

Позволяет экстрагировать информацию об авторе и датах модификации из комментариев в CVS формате. Например:

@cvs($Date: 2004/04/20 02:01:52 $)

@param(идентификатор описание), @return(описание), @returns(описание) и @raises(идентификатор описание)

Эти теги используются в описаниях процедур и функций (в том числе — методов). Описывают соответственно параметры, возвращаемое значение и возможные исключения. “@return” и “@returns” — синонимы.

@member(идентификатор описание) и @value(идентификатор описание)

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

type
  { Описание типа }
  MyEnum = (
    { описание Val1 }
    Val1,
    { описание Val2 }
    Val2,
    . . .
  );

Пишем так:

type
  { Описание типа
    @value(Val1 описание Val1)
    @value(Val2 описание Val2)
    . . .
  }
  MyEnum = (
    Val1,
    Val2,
    . . .
  );

Что более читаемо внутри самих исходников. Точно также и с тегом “@member”, который применим как к полям, так и к методам и свойствам.

Гиперссылки

Вполне естественно, что PasDoc автоматически генерирует гиперссылки между описаниями программных элементов. Степень автоматизма может быть разной — см. “--auto-link”.

Для начала рассмотрим явные ссылки:

@link(идентификатор текст)

Вставляет непосредственную ссылку на описание идентификатора. Замещающий текст может отсутствовать, при этом ссылка будет представлять собой сам идентификатор, возможно — составной (типа “UnitName.Identifier”) — в зависимости от состояния ключа “--link-look”.

@seealso(идентификатор текст)

Аналогично предыдущему создает ссылку на соответствующий элемент, но не в месте своего появления, а в отдельной секции «See also» (или «См. также») — аналогично, например, тегу “@raises”.

Если включен ключ “--auto-link”, PasDoc будет генерировать гиперссылки везде, где ему встретится объявленный идентификатор, что позволяет избежать явного указания “@link”, но не всегда удобно — идентификатор может совпадать с каким-то общеупотребимым словом, которое встречается в тексте само по себе². Чтобы и автоссылками воспользоваться и лишних ссылок избежать, следует обратить внимание на следующие теги, управляющими режимом автоматических ссылок.

@noAutoLink(текст)

Данный тег запрещает использовать автоматическое определение идентификаторов в тексте параметра. Внутри тега ссылки можно указать лишь явно.

@noAutoLinkHere

Здесь «here» следует понимать как «сюда», а не «здесь». Этот тег следует помещать в описание того элемента, на который не должно быть автоматических ссылок (т.е. объекта с идентификатором типа “Add”, “This” и т.д.). В этом случае данный идентификатор не определяется при автоматическом распознавании, но на него можно по прежнему сослаться явным образом — тегом “@link”.

Отдельно хотелось бы отметить ряд контекстно-зависимых ссылок — это теги без параметров, которые в тексте заменяются значениями (и ссылками), зависящими от того элемента, в описании которого они были употреблены.

@name и @classname

Эти теги не создают гиперссылки, а всего лишь вставляют вместо себя идентификатор текущего элемента и класса (интерфейса, записи и т.д.), к которому он принадлежит.

@inherited и @inheritedClass

Соотвественно вставляют идентификатор (с гиперссылкой) унаследованного элемента и класса-предка. В описании класса тег “@inherited” действует так же, как “@inheritedClass”; в описании элемента он вставляет полный идентификатор перекрытого элемента (вида “ClassName.ItemName”) с соответствующей ссылкой.

Пример:

{ @name — это метод @classname, который перекрывает @inherited,
  чтобы кое-что сделать иначе... }

Форматирование

Следующие теги предназначены для форматирования и оформления описаний, генерируемых программой PasDoc.

@bold(текст) и @italic(текст)

Выделяют текст полужирным шрифтом и курсивом соотвественно. Параметр этих тегов не может содержать конец абзаца — пустую строку. Теги могут быть вложенными.

@code(текст)

Данный тег форматирует текст-параметр как фрагмент кода внутри строки — в случае выходного формата HTML это будет соответственно тег “ ... ”. Внутри тега нельзя использовать пустые строки, зато можно использовать прочие PasDoc-теги.

@preformatted(текст)

Сохраняет разбивку текста-параметра, а также все специальные символы внутри. В частности, внутри параметра данного тега все прочие теги PasDoc будут выведены, как обычные слова.

В параметре могут встречаться пустые строки — в результат они попадут сами по себе, а не как конец абзаца. При этом следует помнить об открывающих и закрывающих скобках — если не соблюден баланс, тег, как и любой другой, не будет закрыт или будет закрыт досрочно.

@longcode(маркер текст маркер)

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

Маркер в начале и в конце тега нужен для совместимости с предыдущими версиями. Им может быть любой символ, кроме скобок, но в документации рекомендовано использовать символ “#”. Данный маркер никакого отношения к маркеру PasDoc-комментариев (см. “--marker”) не имеет.

Несколько особняком стоят теги, вставляющие особым образом форматированные конструкции и специальные символы.

Тире и @-

PasDoc для вставки тире использует конструкции, позаимствованные из LaT_EX: длинное тире («—» — “—”) — “---”; короткое тире («–» — “–”) — “--”; одиночный дефис “-” дефис («-») и обозначает. Если идущие подряд дефисы не следует превращать в тире, используется запись “@-”, которая всегда обозначает дефис, независимо от контекста.

@br

Тег вставляет принудительный разрыв строки.

@nil, @true и @false

Вставляют форматированные “Nil”, “True” и “False” соответственно.

Кроме описанного простого форматирования PasDoc позволяет создавать различные списки (упорядоченные, неупорядоченные и определений), а также таблицы. Возможности их форматирования обширны и выходят за рамки обзорной статьи. Интересующиеся могут обратиться к документации на http://pasdoc.sourceforge.net/.

Специальные

Нижеприведенные теги используются для специальных целей и трудно поддаются классификации.

@deprecated

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

@exclude

Исключает элемент из генерируемой документации.

@html(html-код) и @latex(latex-код)

Эти два тега позволяют вставить некий код непосредственно в HTML- или LaT_EX-вывод программы. Таким образом можно использовать произвольные конструкции, например — вставлять ссылки на внешние ресурсы. См. ключ командной строки “--format”.

Расширенные возможности

Директивы компилятора

Собственно, нас интересуют не все директивы, а только те, которые способны повлиять на состав документации. Это, во-первых, директивы условной компиляции, и во-вторых, директивы включения файла ({$INCLUDE ...}).

Условные директивы

PasDoc поддерживает директивы условной компиляции частично — на том уровне, который был доступен еще в Turbo Pascal — {$IFDEF ...}. Условия типа {$IFOPT ...} или {$IF ...} с выражением пока не поддерживаются. Для управления символами условной компиляции используются ключи командной строки “--define” и “--conditionals”: первый позволяет определить символы непосредственно в командной строке, а второй — использовать файл, в котором они перечислены.

{$INCLUDE ...}

PasDoc поддерживает включения файлов директивой {$INCLUDE ...}, поиск файлов производится в каталоге исходников и каталогах, указанных ключом “--include”.

Внешние файлы

Описания

Описания программных элементов могут быть размещены не только в комментариях внутри исходников, но и во внешнем файле. Формат файла следующий:

#Item1
Описание Item1
#Item2
Описание Item2
. . . . .

Идентификаторы Item1, Item2 и т.д. должны быть в полной форме — с указанием через точку модуля, класса и проч. (вида “#UnitName.ClassName.MethodName”). В тексте описаний — строках которые не начинаются с “#” — можно использовать PasDoc-теги точно так же, как и в описаниях-комментариях.

Файл описаний подключается параметром командной строки “--description”.

Такие внешние описания можно использовать, например, для генерации документации на нескольких языках, хотя в этом отношении более удачным выбором представляется утилита FPDoc, идущая в составе дистрибутива FPC и поддерживающая синхронизацию, обновление, объединение и т.д. своих файлов описаний (но не поддерживающая получение описаний из комментариев, и существенно более сложная в использовании).

HTML-шапка и подвал

Если выходной формат — HTML или HtmlHelp, в начало и конец каждой страницы можно добавить определенные фрагменты (с копирайтом, ссылкой на сайт и чем угодно еще). Данные фрагменты оформляются в виде отдельных файлов и подключаются ключами “--header” и “--footer”. Содержимое этих файлов должно представлять собой фрагменты непосредственно html-кода, которые будут размещены сразу после “<body>” и сразу перед “</body>” соответственно⁴.

«Введение» и «Заключение»

PasDoc позволяет добавить к документации в целом «главы» «Introduction» и «Conclusion» — «Введение» и «Заключение» соответственно. Они представляют собой текстовые файлы, которые подключаются посредством ключей “--introduction” и “--conclusion”. Синтаксис данных файлов тот же, что у блоков комментариев-описаний, за исключением нескольких дополнительных тегов, которые в обычных описаниях встречаться не должны.

@anchor(идентификатор)

Устанавливает метку-«якорь», на которую можно ссылаться из других частей документации по идентификатору (посредством тегов “@link” и “@seealso”). Идентификатор должен соответствовать требованиям языка Паскаль.

@section(уровень идентификатор заголовок)

Создает подраздел введения/заключения (а также подподраздел и т.д.). Вложенность раздела определяется числом в первом параметре тега — данный уровень должен быть больше или равен 1. Уровень 1 соответствует “

...

” в HTML и “\section{...}” в LaT_EX. Второй параметр — идентификатор — позволяет ссылаться на данный подраздел посредством тега “@link”. Третий параметр — отображаемый заголовок.

@tableOfContents(уровень)

Данный тег вставляет содержание, формируемое тегами “@section” в текст. Необязательный параметр — уровень — позволяет ограничить глубину вложенности элементов содержания. Данный тег работает только при выходном формате HTML.

@title(текст) и @shorttitle(текст)

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

Для того, чтобы сослаться на введение или заключение откуда-то из текста описаний следует использовать тег “@link” с именем файла, содержащего введение/заключение, без расширения.

Прочие вкусности

Поиск

PasDoc позволяет встроить в html-результаты поиск, построенный на «Tipue Search Engine» — JavaScript-движке для локального поиска. Ищет достаточно адвекватно (в том числе — на русском), но при больших объемах могут быть и тормоза.

См. ключ “--use-tipue-search”.

GraphViz

GraphViz — это такая программа, которая по текстовым данным, предоставляемым, например, утилитой PasDoc, строит графическое представление некоего графа. PasDoc умеет использовать такое представление для иерархии классов и зависимостей модулей. Подробности см. в документации.

Проверка орфографии

PasDoc позволяет подключить проверку орфографии посредством aspell. Подробности см. в документации.

Синтаксис командной строки

Общий вид командной строки следующий:

pasdoc [‹опции›] [‹файлы›]

Где ‹файлы› — произвольное количество имен исходных файлов и масок (например, *.pp), а ‹опции› — комбинация из нижеперечисленных ключей.

Ключи

--help

--version

--verbosity

--define

--description

--conditionals

--include

--source

--html-help-contents

--footer

--header

--name

--title

--format

--output

--exclude-generator

--language

--staronly

--marker

--marker-optional

--numericfilenames

--visible-members

--write-uses-list

--graphviz-uses,
--graphviz-classes,
--link-gv-uses,
--link-gv-classes

--abbreviations

--aspell

--spell-check-ignore-words

--cache-dir

--link-look

--full-link

--css

--auto-abstract

--use-tipue-search

--sort

--introduction,
--conclusion

--latex-head

--implicit-visibility

--no-macro

--auto-link

Заключение

Общее впечатление от программы PasDoc — более чем благоприятное. Свою основную задачу — формирование документации из комментариев в исходниках — она выполняет вполне успешно.

Пока писалась данная статья, на «PasDoc Wiki» появилась информация о новых тегах, которые будут доступны в следующем релизе — “@image” и “@include”. Первый служит для вставки картинок, а второй, соответственно, для вставки в описание текста из внешнего файла. Поскольку в текущем релизе они еще недоступны, в материал статьи я их решил не вставлять. В общем — следите за обновлениями на официальном сайте.

Есть некоторые недоработки в русской локализации… Напомню, что проект открытый и принять посильное участие может каждый желающий. Полагаю, поддержкой русского языка должно озаботься именно русскоязычное сообщество…

В общем и целом, для быстрого создания документации из откомментированных исходников PasDoc — оптимальный выбор. Если же потребности немного иные — многоязычность, версионность, более гибкое оформление — есть FPDoc, входящий в состав дистрибутива Free Pascal. О нем я надеюсь написать в ближайшее время.

Примечания

1) Различия в синтаксисе Delphi и FPC с точки зрения PasDoc совсем незначительны и мы их рассматривать не будем.

2) Само собой, это относится к комментариям на языках, использующих латиницу.

3) В настоящее время (версия 0.10.0) данная пометка не локализована.

4) Строго говоря, фрагмент, вставляемый параметром “--footer”, не всегда размещается непосредственно перед “</body>” — это зависит от наличия «информации о генераторе» — см. ключ “--exclude-generator”.