Янв19

Модул PODs

Отправлено Январь 19, 2012 в 18:28

Документацията за Perl модули е написана по прост език за маркиране, наречена POD (Plain Old Documentation).
Тази страница показва как да напишете POD за Perl модул. Ако се придържате към този стил, то той ще бъде по-лесно за другите да четат и разбират вашата документация.

h2xs слага скелет 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 раздел дава текста на всяка грешка
посланието на модула може да генерира,
и обяснява значението му.Съобщения за грешки са класифицирани, както следва:

(W)
Предупреждение (по избор)
(D)
Осъждане (по избор)
(S)
Тежка предупреждение (задължително)
(F)
Фатална грешка (трапабл)
(X)
Много фатална грешка (не трапабл)
 
=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 секции и ще ги игнорира.

Originally at http://world.std.com/~swmcd/steven/perl/module_pod.html. Translated by Allscnmag.