1. Проектная документация
Как сделать так, чтобы вас не
проклинали потомки

2. Зачем нам её писать?

3. Глупый вопрос

4. Зачем?
Структуру большого проекта не получится держать в
голове
Разбираться в чужом коде - то ещё удовольствие
Возможность подключить к проекту новых
программистов

5. Perl
начнем с примера:
package Test;
sub do_nothing{}
sub do_something{...}
1;

6. Немного теории
Документация в Perl - это та часть файла, которая
находится между
=чтоугодно
и
=cut
Например
=pod
Какой-то текст
=cut

7. Структура POD-документа
Обычный блок текста
Дословный блок (отступ)
Управляющий блок (=pod, =head1)

8. Управляющий блок
=headN text - заголовок 1-4го уровня
=pod - начало обычного блока текста
=over отступ - установка отступа
=item - элемент списка
=back - возврат предыдущего отступа

9. Форматирование
I<TEXT> - курсив (<i></i>)
B<TEXT> - жирный (<b></b>)
C<TEXT> - код
L<LINK> - ссылка на секцию либо модуль
L<LINK|TITLE> - установка кастомного TITLE
E<gt> - escapes like HTML
F<.zshrc> - имя файла

10. Документируем модуль
package Test;
=head1 NAME
Test - краткое описание модуля
=head1 SYNOPSYS
use Test;
... some example ...
=head1 DESCRIPTION
Большое и длинное описание модуля.
=head1 METHODS
=cut
...дальше следует код модуля...
=head1 AUTHOR
Andrey Kostenko <andrey@kostenko.name>
=head1 LICENSE
Microsoft EULA
=cut

11. Документируем метод
=head2 do_nothing
Args: none
Returns: nothing
Actually does nothing
=cut
sub do_nothing {
}
=head2 do_something
Args: $variable, %hash
Returns: some data
=cut

12. Либо
Создаём файл с расширением .pod и пишем туда
документацию, не связанную с каким-либо кодом

13. Спасибо, Капитан Очевидность
Возможно, я не рассказал вам ничего нового.
Но я очень надеюсь, что вы задумаетесь о
необходимости документирования кода

14. =head1 AUTHOR
I<Andrey Kostenko>
L<http://kostenko.name>
L<mailto:a.kostenko@rambler-co.ru>