Original:http://world.std.com/~swmcd/steven/perl/module_pod.html

Модуль POD

Документация для модулей Perl написана на простом языке разметки под названием POD (обычная старая документация).

На этой странице показано, как написать 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, такие как Creation , Access и Utility .

=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 дает текст каждого сообщения об ошибке, который может генерировать модуль, и объясняет его значение.

Сообщения об ошибках классифицируются следующим образом:

(Вт)
Предупреждение (необязательно)
(D)
Отклонение (необязательно)
(S),
Суровое предупреждение (обязательно)
(F)
Неустранимая ошибка (ловушка)
(ИКС)
Очень фатальная ошибка (non-trappable)
=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

Словенский перевод любезно предоставлен Николаем Хессом


Стивен У. Макдугалл / резюме / swmcd@world.std.com / 1997 2 июня