perl pod
TRANSCRIPT
![Page 1: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/1.jpg)
Проектная документация
Как сделать так, чтобы вас не проклинали потомки
![Page 2: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/2.jpg)
Зачем нам её писать?
![Page 3: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/3.jpg)
Глупый вопрос
![Page 4: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/4.jpg)
Зачем?
Структуру большого проекта не получится держать в головеРазбираться в чужом коде - то ещё удовольствиеВозможность подключить к проекту новых программистов
![Page 5: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/5.jpg)
Perl
начнем с примера:
package Test;
sub do_nothing{}
sub do_something{...}
1;
![Page 6: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/6.jpg)
Немного теории
Документация в Perl - это та часть файла, которая находится между=чтоугоднои=cut
Например
=podКакой-то текст=cut
![Page 7: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/7.jpg)
Структура POD-документа
Обычный блок текстаДословный блок (отступ) Управляющий блок (=pod, =head1)
![Page 8: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/8.jpg)
Управляющий блок
=headN text - заголовок 1-4го уровня=pod - начало обычного блока текста=over отступ - установка отступа=item - элемент списка =back - возврат предыдущего отступа
![Page 9: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/9.jpg)
Форматирование
I<TEXT> - курсив (<i></i>)B<TEXT> - жирный (<b></b>)C<TEXT> - кодL<LINK> - ссылка на секцию либо модуль L<LINK|TITLE> - установка кастомного TITLEE<gt> - escapes like HTMLF<.zshrc> - имя файла
![Page 10: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/10.jpg)
Документируем модуль
package Test;=head1 NAMETest - краткое описание модуля=head1 SYNOPSYS use Test; ... some example ...=head1 DESCRIPTIONБольшое и длинное описание модуля. =head1 METHODS=cut...дальше следует код модуля...=head1 AUTHORAndrey Kostenko <[email protected]>=head1 LICENSEMicrosoft EULA=cut
![Page 11: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/11.jpg)
Документируем метод
=head2 do_nothingArgs: noneReturns: nothingActually does nothing=cutsub do_nothing { } =head2 do_somethingArgs: $variable, \%hashReturns: some data=cut
![Page 12: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/12.jpg)
Либо
Создаём файл с расширением .pod и пишем туда документацию, не связанную с каким-либо кодом
![Page 13: Perl POD](https://reader038.vdocuments.site/reader038/viewer/2022100601/55795942d8b42ab6648b4cb7/html5/thumbnails/13.jpg)
Спасибо, Капитан Очевидность
Возможно, я не рассказал вам ничего нового. Но я очень надеюсь, что вы задумаетесь о необходимости документирования кода