Perl POD

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

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

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

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

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> - установка кастомного TITLE E<gt> - escapes like HTML F<.zshrc> - имя файла

Документируем модуль 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

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

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

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

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

http://kostenko.name	87
http://www.slideshare.net	17
http://rstream.gugu.dev.rambler.ru:31336	1
http://webcache.googleusercontent.com	1

Perl POD

by Андрiй Костенко on May 17, 2009

Accessibility

Categories

Tags

Upload Details

Usage Rights

4 Embeds 106

Statistics

Perl POD — Presentation Transcript