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

Струкі Модуль

Дакументацыя для Perl модуляў пішацца ў просты разметкі мову пад назвай (старыя дакументы).

Гэтая старонка паказвае, як напісаць модуль для Perl-модуля. Калі прытрымлівацца гэтага стылютады гэта будзе лягчэй для іншых, каб чытаць і разумець дакументацыю.

h2xs ставіць пад шкілет у канцы .pm файл, які ён пішаЧытайце модуляў ў існуючыя модулі дадатковыя прыклады.

=head1 NAME
 
Geometry::Circle - manages a circle

Гэты NAME раздзел дае імя модуля і Апісанне Ў адзін радок.

Назва і апісанне, падзеленых злучком. Важна прытрымлівацца гэтага фармату, так што РМО могуць быць ператвораныя ў адпаведную старонку чалавека.

=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

 

Геаметрыя::круг кіруе кругі.

Метады прызначаныя для стварэння

кругі і вылічальнай сваіх месцах.

Гэта апісанне модуля.

Ён павінен быць напісаны ў тэрмінах, якія маюць дачыненне да карыстача, а не праграміст.

  • Што ён робіць для карыстальніка?
  • Як вы яго выкарыстоўваеце?
  • Якія аб'екты ён падтрымлівае?
  • Якімі метадамі гэта забяспечыць?
=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 рубрыкітакія як CreationAccess і 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 раздзел дае тэкст кожную памылку паведамленне модуль можа генеравацьі тлумачыць яе сэнс.

Паведамленні пра памылкі падпадзяляюцца наступным чынам:

(Вт)

Папярэджанне (апцыянальна)

(Д)

Забарона (апцыянальна)

(З)

Сур'ёзнае папярэджанне (абавязковае)

(Ф)

Фатальная памылка (перехватываемые)

(Х)

Вельмі фатальная памылка (не перахапляць)

=head1 AUTHOR
 
A. U. Thor, a.u.thor@a.galaxy.far.far.away

Вы павінны паказаць сваё імя і адрас электроннай пошты, у выпадку, калі хто-то захоча звязацца з Вамі з нагоды модуля.

=head1 SEE ALSO
 
perl(1), Geometry::Square

Гэта звычайны спіс праграм і модуляў.

=cut

У =cut радку пазначае канец пад тэкст.

Некаторыя людзі размяркоўваюць ўчасткі пад ўсёй іх зыходны код. Perl не распазнае раздзелы pod і ігнаруе іх.