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

Как сделать так, чтобы вас не проклинали потомки

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

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

Зачем?

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

Perl

начнем с примера:

package Test;

sub do_nothing{}

sub do_something{...}

1;

Немного теории

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

Например

=podКакой-то текст=cut

Структура POD-документа

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

Управляющий блок

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

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

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

Документируем модуль

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

Документируем метод

=head2 do_nothingArgs: noneReturns: nothingActually does nothing=cutsub do_nothing { } =head2 do_somethingArgs: $variable, \%hashReturns: some data=cut

Либо

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

Спасибо, Капитан Очевидность

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

=head1 AUTHORI<Andrey Kostenko>

L<http://kostenko.name> L<mailto:a.kostenko@rambler-co.ru>