perl pod
Post on 11-Jun-2015
2.391 Views
Preview:
TRANSCRIPT
Проектная документация
Как сделать так, чтобы вас не проклинали потомки
Зачем нам её писать?
Глупый вопрос
Зачем?
Структуру большого проекта не получится держать в головеРазбираться в чужом коде - то ещё удовольствиеВозможность подключить к проекту новых программистов
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>
top related