http://www.perlmonks.org?node_id=558831

Translated to spanish from [id://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.

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:

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:

Entidades

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

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!