Perl POD

2,712 views

Published on

Published in: Technology
1 Comment
2 Likes
Statistics
Notes
No Downloads
Views
Total views
2,712
On SlideShare
0
From Embeds
0
Number of Embeds
134
Actions
Shares
0
Downloads
16
Comments
1
Likes
2
Embeds 0
No embeds

No notes for slide

Perl POD

  1. 1. Проектная документация Как сделать так, чтобы вас не проклинали потомки
  2. 2. Зачем нам её писать?
  3. 3. Глупый вопрос
  4. 4. Зачем? Структуру большого проекта не получится держать в голове Разбираться в чужом коде - то ещё удовольствие Возможность подключить к проекту новых программистов
  5. 5. Perl начнем с примера: package Test; sub do_nothing{} sub do_something{...} 1;
  6. 6. Немного теории Документация в Perl - это та часть файла, которая находится между =чтоугодно и =cut Например =pod Какой-то текст =cut
  7. 7. Структура POD-документа Обычный блок текста Дословный блок (отступ) Управляющий блок (=pod, =head1)
  8. 8. Управляющий блок =headN text - заголовок 1-4го уровня =pod - начало обычного блока текста =over отступ - установка отступа =item - элемент списка =back - возврат предыдущего отступа
  9. 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. 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. 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. 12. Либо Создаём файл с расширением .pod  и пишем туда документацию, не связанную с каким-либо кодом
  13. 13. Спасибо, Капитан Очевидность Возможно, я не рассказал вам ничего нового.   Но я очень надеюсь, что вы задумаетесь о необходимости документирования кода
  14. 14. =head1 AUTHOR I<Andrey Kostenko> L<http://kostenko.name> L<mailto:a.kostenko@rambler-co.ru>

×