Original:http://world.std.com/~swmcd/steven/perl/module_pod.html
На этой странице показано, как написать POD для модуля Perl. Если вы придерживаетесь этого стиля, тогда другим будет легче читать и понимать вашу документацию.
h2xs
помещает скелет POD в конец файла .pm
который он пишет.
Прочтите POD в существующих модулях для дополнительных примеров.
=head1 NAME Geometry::Circle - manages a circle |
Раздел NAME дает имя модуля и однострочное описание.
Имя и описание разделены тире. Важно придерживаться этого формата, чтобы POD можно было преобразовать в соответствующую страницу руководства. |
=head1 SYNOPSIS use Geometry::Circle $circle = new Geometry::Circle $x, $y, $r ($x, $y) = $circle->center; $radius = $circle->radius; $area = $circle->area $pi = $Geometry::Circle::PI; |
Раздел SYNOPSIS показывает основные этапы использования модуля: оператор использования, любые подпрограммы, методы или переменные класса и все методы объектов.
Вызов методов должен указывать их параметры и возвращаемые значения.
Отметьте каждую строку в сводке. Это делает его дословным абзацем и гарантирует, что ваше выравнивание будет сохранено. |
=head1 REQUIRES Perl5.8.8, Exporter, Geometry::Point |
Раздел REQUIRES сообщает пользователю, что им нужно, чтобы использовать модуль.
|
=head1 EXPORTS Nothing |
Раздел EXPORTS сообщает пользователю, что модуль будет делать с их пространством имен, если они его use .
|
=head1 DESCRIPTION Geometry::Circle manages circles. Methods are provided for creating circles and computing their areas. |
Это описание модуля.
Он должен быть написан в терминах, которые имеют отношение к пользователю, а не программисту.
|
=head1 METHODS =head2 Creation =over 4 =item new Geometry::Circle $x, $y, $radius Creates and returns a new Geometry::Circle object with center ($x, $y) and radius $radius. =back =head2 Access =over 4 =item $circle->center Returns a list of the x,y coordinates of the center of the circle. In scalar context, returns an array reference. =item $circle->radius Returns the radius of the circle. =item $circle->area Returns the area of the circle. =back |
Раздел METHODS перечисляет и описывает каждый метод в классе.
Вы также можете организовать методы под заголовками уровня 2, такие как |
=head1 CLASS VARIABLES =over 4 =item $Geometry::Circle::PI The ratio of the circumference of a circle to its diameter. =back |
Раздел CLASS VARIABLES перечисляет любые переменные пакета в API.
|
=head1 DIAGNOSTICS =over 4 =item Negative radius (F) A circle may not be created with a negative radius. =back |
Раздел DIAGNOSTICS дает текст каждого сообщения об ошибке, который может генерировать модуль, и объясняет его значение.
Сообщения об ошибках классифицируются следующим образом:
|
=head1 AUTHOR A. U. Thor, a.u.thor@a.galaxy.far.far.away | Вы должны указать свое имя и адрес электронной почты, если кто-то должен связаться с вами относительно модуля. |
=head1 SEE ALSO perl(1), Geometry::Square | Это обычный список связанных программ и модулей. |
=cut |
Строка =cut обозначает конец текста POD.
Некоторые люди распространяют разделы POD по всему исходному коду. Perl распознает разделы POD и игнорирует их. |
Болгарский перевод любезно предоставлен All Science
Французский перевод любезно предоставлен Coupon Addict
Немецкий перевод любезно предоставлен gameperiod.com
Хинди перевод любезно предоставлен Прити Агарвал
Японский перевод любезно предоставлен Daily Deals Coupon
Перевод с итальянского перевода с сайта Search-Sos
Словенский перевод любезно предоставлен Николаем Хессом