Встроенная документация

В Perl нет многострочных комментариев, подобных /* … */ в языке C или Java. (Хотя эту возможность можно добавить, если подключить модуль Acme::Comment, доступный в хранилище модулей CPAN.) Но если требуются комментарии из нескольких строк, то можно воспользоваться командами системы документирования Perl, называемой POD (от английского "Plain Old Documentation" - "старая добрая документация"). Такой многострочный комментарий можно записать в виде

=pod Знак = должен располагаться в самом начале строки. Текст этого комментария фактически является документацией в формате POD, встроенной в текст программы. Конец комментария (=cut) также должен быть в начале строки. =cut

POD представляет из себя систему разметки текста, в том числе программной документации, который можно просматривать, печатать или конвертировать в другой текстовый формат, например, в HTML. Документация может храниться в текстовых файлах, обычно с суффиксом pod. Но благодаря тому, что компилятор perl игнорирует текст, окруженный командами POD, документацию можно встраивать в нужные места исходного текста программы. Вот наиболее часто используемые команды POD для оформления документации на программу, которые встречаются при чтении исходных текстов на Perl:

=pod Начало документации (использовать не обязательно). =headN текст заголовка Заголовок N-го уровня. Уровень N может быть от 1 до 4. =over N Абзац с отступом в N знаков, например, начало списка. =item заглавие элемента Начало элемента списка. =back Окончание списка. =cut Окончание POD-документации, возврат к тексту программы.

Прочитать встроенную в программу POD-документацию в отформатированном виде можно с помощью поставляемой утилиты просмотра:

perldoc program_with_pod

Описание в формате POD можно преобразовать в web-страницу поставляемой в комплекте с perl утилитой:

pod2html --outfile=program.html program_with_pod

Конечно, возможностей у системы POD гораздо больше. Узнать о них можно из поставляемой с дистрибутивом Perl документации, прочитав ее с помощью утилиты просмотра документации:

perldoc perlpod

В этой лекции изложены сведения о литералах и переменных - "молекулах" языка Perl. Они служат основой для создания выражений-"клеток", по воле программиста превращающихся в "живые организмы" - программы на языке Perl, многие из которых проживают долгую жизнь, развиваясь и принося пользу людям. В нескольких следующих лекциях будет излагаться "анатомия" Perl, без знания которой нельзя приступать к написанию программ...

perldoc perlpod

В этой лекции изложены сведения о литералах и переменных - "молекулах" языка Perl. Они служат основой для создания выражений-"клеток", по воле программиста превращающихся в "живые организмы" - программы на языке Perl, многие из которых проживают долгую жизнь, развиваясь и принося пользу людям. В нескольких следующих лекциях будет излагаться "анатомия" Perl, без знания которой нельзя приступать к написанию программ...

Содержание раздела