homeyou

Technical Translations by Artur Weber & Adelina Domingos

Adelina Domingos
Artur Weber
Original Article: Module PODs
Author: world.std.com
Module PODs

Módulo PODs

A documentação dos módulos Perl está escrita em uma linguagem de marcação simples chamada POD (Documentação antiga simples).

Esta página mostra como escrever um POD para um módulo Perl. Se você aderir a esse estilo, será mais fácil para outros ler e entender sua documentação.

h2xs coloca um esqueleto POD no final do .pm arquivo que ele escreve. Leia os PODs em módulos existentes para obter exemplos adicionais. 

=head1 NAME

Geometry::Circle - manages a circle
O NAME seção fornece o nome do módulo e uma descrição de uma linha.

O nome e a descrição estão separados por um dash. É importante aderir a este formato para que o POD possa ser convertido em uma página de manual adequada. 

=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;
A SYNOPSIS A seção mostra as etapas essenciais no uso do módulo: a indicação de uso, qualquer sub-rotinas, métodos de classe ou variáveis e todos os métodos de objeto. As chamadas de método devem indicar seus parâmetros e valores de retorno.

Descarte cada linha na sinopse. Isso torna um parágrafo literal e garante que seu alinhamento seja preservado. 

=head1 REQUIRES

Perl5.8.8, Exporter, Geometry::Point
A REQUIRES A seção informa ao usuário o que eles precisarão para usar o módulo. 
=head1 EXPORTS

Nothing
A EXPORTS A seção informa ao usuário o que o módulo fará no seu namespace se eles use it. 
=head1 DESCRIPTION

Geometry::Circle manages circles.  
Methods are provided for creating 
circles and computing their areas.
Esta é uma descrição do módulo.

Deve ser escrito em termos que sejam relevantes para o usuário e não para o programador.

  • O que ele faz para o usuário?
  • Como você usa isso?
  • Em que objetos ele suporta?
  • Quais são os métodos fornecidos? 
=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
O METHODS seção lista e descreve cada método na classe.

Você pode ainda organizar métodos em rubricas de nível 2, como Creation, Access e Utility. 

=head1 CLASS VARIABLES

=over 4

=item $Geometry::Circle::PI

The ratio of the circumference 
of a circle to its diameter.

=back
A CLASS VARIABLES seção lista as variáveis de pacote na API. 
=head1 DIAGNOSTICS

=over 4

=item Negative radius

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

=back
O DIAGNOSTICS seção fornece o texto de cada mensagem de erro que o módulo pode gerar e explica seu significado.

As mensagens de erro são classificadas da seguinte forma:

(W)
Um aviso (opcional)
(D)
Uma depreciação (opcional) Um aviso (opcional)
(S)
Um aviso severo (obrigatório)
(F)
Um erro fatal (interceptável)
(X)
Um erro muito fatal (não interceptável) 
=head1 AUTHOR

A. U. Thor, [email protected]
Você deve incluir seu nome e endereço de e-mail, caso alguém precise contatá-lo sobre o módulo. 
=head1 SEE ALSO

perl(1), Geometry::Square
Esta é a lista habitual de programas e módulos relacionados. 
=cut
A =cut linha indica o fim do texto POD.

Algumas pessoas distribuem seções POD ao longo de seu código fonte. Perl reconhece as seções POD e as ignora.