Módulo PODs

Source- Módulo PODs

Author- Steven W. McDougall 

 

La documentación para los módulos de Perl está escrita en un lenguaje simple llamado POD (Plain Old Documentation)

Esta página muestra como escribir un POD para un modulo de Perl. Si se adapta a este estilo, entonces será más fácil para otras personas leer y entender su documentación.

h2xs coloca una plantilla POD al final del archivo .pm que escribe. Lea los PODs en los módulos existentes para ejemplos adicionales.

=head1 NAME

 

Geometry::Circle – manages a circle

La sección NAME proporciona el nombre del módulo en una descripción de una línea.

El nombre y la descripción son separados por un guion. Es importante adaptarse a este formato para que el POD pueda convertirse en una página apropiada.

=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;

 

La sección SYNOPSIS muestra los pasos esenciales en usar el módulo: la sentencia use, cualquier subrutina, métodos de clases o variables, y todos los métodos de los objetos. Las llamadas de los métodos deben indicar sus parámetros y retornar valores.

Identa cada línea en la synopsis. Esto hace que sea un párrafo textual, y asegura que preservará su alineación.

=head1 REQUIRES

 

Perl5.8.8, Exporter, Geometry::Point

 

La sección REQUIRES le dice al usuario que necesitara para poder usar el módulo.

=head1 EXPORTS

 

Nothing

 

La sección EXPORTS le dice al usuario que hará el módulo a su namespace (espacio de nombres) si lo usa

=head1 DESCRIPTION

 

Geometry::Circle manages circles.

Methods are provided for creating

circles and computing their areas.

 

Esto es una descripción del módulo.

Debe ser escrito en términos que sean relevantes para el usuario, en lugar del programador.

  • ¿Qué hace para el usuario?
  • ¿Cómo lo usa?
  • ¿Qué objetos soporta?
  • ¿Qué métodos provee?
=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

 

La sección METHODS lista y describe cada método en la clase

Puede organizar más métodos bajo encabezados de nivel 2, tales como Creation, Access  y Utility.

=head1 CLASS VARIABLES

 

=over 4

 

=item $Geometry::Circle::PI

 

The ratio of the circumference

of a circle to its diameter.

 

=back

 

La sección CLASS VARIABLES lista cualquier variable de paquetes en la API.

=head1 DIAGNOSTICS

 

=over 4

 

=item Negative radius

 

(F) A circle may not be created with a negative radius.

 

=back

 

La sección DIAGNOSTICS proporciona el texto de cada mensaje de error que el módulo pueda generar, y explica su significado.

Los mensajes de error se clasifican de la siguiente forma:

(W)     Una advertencia (opcional)

 

(D)      Una deprecación (opcional)

 

(S)      Una advertencia grave (obligatorio)

 

(F)      Un error fatal (capturable)

 

(X)     Un error muy fatal (no capturable)

=head1 AUTHOR

 

A. U. Thor, [email protected]

 

Debe incluir su nombre y dirección de correo electrónico, en caso de que alguien necesite contactarlo con respecto al módulo.

=head1 SEE ALSO

 

perl(1), Geometry::Square

 

Esta es la lista usual de programas y módulos relacionados.

=cut  

La línea =cut denota el fin del texto POD.

Algunas personas distribuyen las secciones POD a través de su código fuente. Perl reconoce las secciones POD y las ignora.

 

Leave a Comment

Your email address will not be published. Required fields are marked *