POD en 5 minutos

[Hue-Bond]

Translated to spanish from Juerd's original POD in 5 minutes.

Plain Old Documentation en 5 minutos

La documentación es importante

Todos el mundo lo sabe, y sabe por qué. Me voy a saltar esta sección porque cualquier discusión detallada de por qué la documentación es importante rompería mi promesa de que se puede aprender a documentar en cinco minutos.

Documentación en Perl

El código fuente en Perl puede contener documentación en formato POD. POD significa "Plain Old Documentation" (documentación simple). Se puede mezclar POD con código, poner todo el POD al principio o ponerlo al final. Sólo depende del gusto de cada uno. Tú eliges.

Encabezados en POD

La estructura lógica es importante, por tanto se suelen usar encabezados. Hay cuatro niveles, y con esto debería llegar. Se usan los comandos =head1 .. =head4 (oficialmente se les llama comandos de párrafo. Son párrafos porque están separados del resto del POD mediante líneas en blanco).

=head1 NOMBRE

My::Module - Un módulo de ejemplo

Secciones habituales

Para mantener las cosas claras, se usan las mismas secciones en todas partes. Ya hemos visto la sección NOMBRE. Sí, es costumbre escribir los párrafos head1 en MAYÚSCULAS. Si haces módulos para CPAN, debes usar este estilo. Si no, o si usas POD para otras cosas que documentación (también es un formato bueno para escribir artículos o informes), queda a tu elección.

• NOMBRE contiene el nombre del módulo o script, un guión y una descripción corta.
• SINOPSIS significa "ver todo junto" y muestra ejemplos de uso.
• DESCRIPCIÓN contiene una descripción larga de lo que hace el módulo y lista sus funciones.
• BUGS o ADVERTENCIAS habla de los bugs o problemas que el usuario debería conocer.
• AGRADECIMIENTOS es donde el autor agracede a los que arreglan bugs y prueban el programa.
• COPYRIGHT o LICENCIA menciona las restricciones de copyright. Sin embargo, no hay que poner toda la GPL :).
• DISPONIBILIDAD anuncia dónde se pueden encontrar versiones más recientes.
• AUTOR explica quién ha hecho el programa, si no lo hace ya la sección COPYRIGHT.
• VÉASE TAMBIÉN refiere al lector a un lugar con más documentación.

Todos estos son para =head1.

Las funciones, métodos y todo eso se explican normalmente en una sección =head2 bajo DESCRIPCIÓN.

Como mínimo, hay que documentar los argumentos que reciben las funciones y los valores que se devuelven. Si hay condiciones necesarias para algo, se deben mencionar. Si una función devuelve undef cuando hay errores, hay que hacérselo saber a la gente.

Está bien escribir frases cortas. Es mejor evitar las largas.

Ejemplos de código

Los párrafos tabulados se toman como código, con la tabulación intacta. ¡Así de fácil!:

=head1 SINOPSIS

    use My::Module;
    my $object = My::Module->new(); 
    print $object->as_string;

Esto se llama un párrafo textual.

Marcado

POD soporta un pequeño conjunto de elementos de marcado. Para mantener mi promesa, me voy a limitar a enumerarlos:

• B<texto en negrita>
• I<texto en cursiva>
• U<texto subrayado>
• C<código>
• B<y se pueden I<anidar>>

También hay F, S, X y Z pero apenas se usan y no merece la pena explicarlos en un tutorial pequeño como este.

Si alguna vez hace falta incluir un carácter '>' dentro de código, hay dos opciones. Si queremos poner $foo->bar con fuente de código, podemos hacer esto:

• C<$foo-E<gt>bar>
• C<< $foo->bar >> (¡los espacios son necesarios!)
• C<<< $foo->bar >>> (¡los espacios son necesarios!)

Entidades

Hemos visto que se puede usar E para entidades. Son como las entidades de HTML; también tenemos estas:

• verbar para una barra vertical.
• sol para una barra (solidus).

Las entidades numéricas pueden ir en decimal, octal (con el prefijo '0') y en hexadecimal (con el prefijo '0x').

Listas

En este caso un ejemplo es mucho más claro que una explicación:

=head2 Métodos

=over 12

=item C<new>

Devuelve un objeto My::Module nuevo.

=item C<as_string>

Devuelve una representación del
objeto en forma de cadena. Sirve
principalmente para depuración.

=back

Como puede verse, se empieza esta lista con =over y la acabamos con =back. Entre ambos comandos hay =items. El número después de =over es el nivel de tabulación, usado principalmente por los renderizadores de texto para conseguir un diseño horizontal. pod2text convierte el ejemplo anterior en:

  Methods
      "new"       Returns a new
                  My::Module object.

      "as_string" Returns a stringified 
                  representation of the 
                  object. This is mainly
                  for debugging purposes.

Otras cositas de POD

Se puede usar L para enlazar a secciones del mismo documento o a otros documentos. POD se termina con =cut para volver a Perl. Hay comandos especiales para los distintos formatos de salida. Para leer la documentación completa de POD, teclear:

perldoc perlpod

Un ejemplo completo

=head1 NOMBRE

My::Module - Un módulo de ejemplo

=head1 SINOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPCIÓN

Este módulo no existe en realidad, se
hizo con el único objetivo de mostrar
cómo funciona POD.

=head2 Métodos

=over 12

=item C<new>

Devuelve un objeto My::Module nuevo.

=item C<as_string>

Devuelve una representación del
objeto en forma de cadena. Sirve
principalmente para depuración.

=back

=head1 AUTOR

Juerd - <http://juerd.nl/>

=head1 VÉASE TAMBIÉN

L<perlpod>, L<perlpodspec>

=cut

Conclusión

Documentar con POD es fácil. ¡A divertirse!