Module PODs
Originalside: http://world.std.com/~swmcd/steven/perl/module_pod.html
Dokumentasjonen for Perl-moduler er skrevet på et enkelt markupspråk kalt POD (Plain Old Documentation).
Denne siden viser hvordan du skriver en POD for en Perl-modul. Hvis du holder deg til denne stilen, vil det være lettere for andre å lese og forstå dokumentasjonen din.
h2xs setter et skjelett POD på slutten av .pm-filen som den skriver. Les POD-ene i eksisterende moduler for flere eksempler.
=head1 NAME
Geometry::Circle - manages a circle
Seksjonen NAME gir navnet på modulen og en en-linjers beskrivelse.
Navnet og beskrivelsen skilles med en bindestrek. Det er viktig å overholde dete formatet slik at POD-en kan konverteres til en ordentlig side.
=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;
Seksjonen SYNOPSIS viser de viktige stegene i bruk av modulen: bruksuttalelsen, eventuelle underrutiner, klassemetoder eller variabler, og alle objekt metoder. Method calls skal angi parametere og returverdier.
Start med et innrykk i hver linje i synopsisen. Dette gjør det til et ordrett avsnitt, og sikrer at justeringen din vil bli bevart.
=head1 REQUIRES
Perl5.8.8, Exporter, Geometry::Point
Seksjonen REQUIRES forteller brukeren hva de vil trenge for å bruke modulen.
=head1 EXPORTS
Nothing
Seksjonen EXPORTS forteller brukeren hva modulen vil gjøre med navnefeltet hvis de bruker den.
=head1 DESCRIPTION
Geometry::Circle manages circles.
Methods are provided for creating
circles and computing their areas.
Dette er en beskrivelse av modulen.
Den burde skrives slik at den er relevant for brukeren, i stedet for programmereren.
Hva gjør den for brukeren?
Hvordan bruker du den?
Hvilke objekter støtter den?
Hvilke metoder gir den?
=head1 METHODS
METHODS seksjonen lister opp og
=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
Beskriver hver metode i klassen.
Du kan videre organisere metoder under level-2 overskrifter, som Creation, Access og Utility.
=head1 CLASS VARIABLES
=over 4
=item $Geometry::Circle::PI
The ratio of the circumference
of a circle to its diameter.
=back
Seksjonen CLASS VARIABLES section lists any package variables in the API.
=head1 DIAGNOSTICS
=over 4
=item Negative radius
(F) A circle may not be created with a negative radius.
=back
Seksjonen DIAGNOSTICS viser teksten til alle feilmeldinger som modulen kan generere, og forklarer betydningen.
Feilmeldinger er klassifisert som følger:
(W)
En advarsel (valgfritt)
(D)
En avskrivning (valgfritt)
(S)
En alvorlig advarsel (obligatorisk)
(F)
En fatal feil (trappable)
(X)
En veldig fatal feil (non-trappable)
=head1 AUTHOR
A. U. Thor, a.u.thor@a.galaxy.far.far.away
Du burde oppgi navn og e-postadresse, i tilfelle noen trenger å kontakte deg angående modulen.
=head1 SEE ALSO
perl(1), Geometry::Square
Dette er den vanlige listen over relaterte programmer og moduler.
=cut
Linen =cut betegner slutten på POD-teksten.
Noen distribuerer POD-seksjoner gjennom hele kildekoden. Perl gjenkjenner POD-seksjonene og ignorerer dem.