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 июня

=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 и игнорирует их.