Программисты обычно не очень любят писать документацию. Одной из причин является то, что программы это простые текстовые файлы, а для составления документации разработчикам приходится использовать какой-то текстовый процессор.
В итоге приходится изучать сам текстовый процессор, а также тратить уйму сил в попытках сделать документ "хорошо оформленным", а не "содержательным".
С Perl все иначе. Обычно вы пишете документацию к вашим модулям прямо в исходном коде, а оформлением занимаются внешние инструменты.
В этой главе Учебника Perl мы рассмотрим POD - Простую старую документацию (Plain Old Documentation), язык разметки, который используют Perl-разработчики.
Кусок perl-кода с POD выглядит примерно так:
#!/usr/bin/perl
use strict;
use warnings;
=pod
=head1 DESCRIPTION
Этот скрипт может принимать 2 параметра. Имя или адрес машины
и команда. Он исполнит команду на данной машине и
выведет результат на экран.
=cut
print "Здесь наш код ... \n";
Если вы сохраните это как script.pl и запустите командой perl script.pl,
Perl проигнорирует все между строками =pod и =cut.
Он исполнит только реальный код.
Напротив, если вы запустите perldoc script.pl, команда perldoc
проигнорирует программный код. Она возьмет все строки между =pod и =cut,
отформатирует их в соответствии с определенными правилами, и отобразит на экране.
Правила эти зависят от вашей операционной системы, но они точно такие же, как и те, что мы изучали в главе про стандартную документацию Perl.
Дополнительная ценность встроенного POD в том, что ваш код всегда будет поставляться с документацией, так как она неразрывно связана с самими модулями и сценариями. Вы также всегда можете пользоваться готовыми инструментами и инфраструктурой, построенными для себя сообществом Perl. Даже для своих собственных целей.
Слишком просто?
Идея в том, что если писать документацию будет несложно, то все больше людей будут ее писать. Вместо изучения текстовых процессоров для создания красивых документов, вы просто вводите текст с несколькими дополнительными тегами, и в итоге получаете хорошо оформленную документацию. (Для примера красивого форматирования документации в POD посмотрите документы Meta CPAN)
Язык разметки
Подробное описание языка разметки POD можно получить, введя команду perldoc perlpod, но язык этот очень прост.
Есть несколько тегов, таких как =head1 и =head2,
обозначающих "очень важный" и "несколько менее важный" заголовки.
Имеется =over для создания отступов и =item
для элементов ненумерованного списка, и еще несколько других.
=cut означает конец раздела POD, а
=pod обозначает его начало. Однако начальный тег строго обязательным не является.
Любая строка, первым символом которой является знак равенства =, будет
воспринята как начало POD раздела, который должен быть закрыт тегом =cut
POD позволяет использовать гиперссылки с помощью тега L<some-link>.
Текст между разметкой будет показан как абзац простого текста.
Если текст начинается не с первого символа строки, то он будет использован как есть, то есть он будет выглядеть именно так, как вы его ввели: длинные строки останутся длинными, а короткие так и будут короткими. Обычно это используется для примеров кода.
Важно помнить, что POD требует пустых строк вокруг тегов. То есть
=head1 Заголовок
=head2 Подзаголовок
Какой-то текст
=cut
будет работать не совсем так, как вы могли бы ожидать.
Внешний вид
Поскольку POD это язык разметки, сам по себе он не определяет как что будет отображено.
Мы просто используем =head1, чтобы отметить нечто важное, или =head2 для менее значимого.
Инструмент, который используется для отображения POD, скорее всего использует символы большего кегля для отображения текста в head1, чем в head2, который в свою очередь будет отображен с использованием большего кегля, чем обычный текст. Выбор за инструментом отображения POD.
Команда perldoc, которая поставляется с Perl, отображает POD как man-страницы. Это очень удобно на Linux.
Но не так хорошо на Windows.
Модуль Pod::Html предоставляет другой инструмент командной строки:
pod2html. Он умеет конвертировать POD в HTML, который можно просматривать прямо в браузере.
Существуют также и другие инструменты, например для преобразования POD в форматы PDF или mobi.
Для кого мы пишем документацию?
После того, как мы научились писать документацию в POD, давайте подумаем, кто будет её читать.
Комментарии (то, что начинается с #) это пояснения для программиста, поддерживающего код. Для человека, которому нужно добавить фичу или пофиксить баг.
Документация в POD пишется для пользователей. Для тех, кому не нужно смотреть в исходники. Для приложения это будут так называемые «конечные пользователи». То есть кто угодно.
В случае Perl модулей, это будут пользователи и другие программисты, которым нужно
создать своё приложение или другой модуль используя ваш. Им также незачем
смотреть в ваши исходники. Им должно быть достаточно
просто прочитать документацию при помощи perldoc, чтобы использовать ваш модуль.
Заключение
В Perl совсем не сложно написать и красивое оформить документацию.
