perltutorial
Hue-Bond
<p><small>Translated to spanish from [id://Juerd]'s original [id://252477].</small></p>
<h1>Plain Old Documentation en 5 minutos</h1>
<h2>La documentación es importante</h2>
<p>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.</p>
<h2>Documentación en Perl</h2>
<p>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.</p>
<h2>Encabezados en POD</h2>
<p>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 <tt>=head1</tt> .. <tt>=head4</tt> (oficialmente se les llama <i>comandos de párrafo</i>. Son párrafos porque están separados del resto del POD mediante líneas en
blanco).</p>
<code>=head1 NOMBRE
My::Module - Un módulo de ejemplo</code>
<h2>Secciones habituales</h2>
<p>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.</p>
<ul>
<li><i>NOMBRE</i> contiene el nombre del módulo o script, un guión y una descripción corta.</li>
<li><i>SINOPSIS</i> significa "ver todo junto" y muestra ejemplos de uso.</li>
<li><i>DESCRIPCIÓN</i> contiene una descripción larga de lo que hace el módulo y lista sus funciones.</li>
<li><i>BUGS</i> o <i>ADVERTENCIAS</i> habla de los bugs o problemas que el usuario debería conocer.</li>
<li><i>AGRADECIMIENTOS</i> es donde el autor agracede a los que arreglan bugs y prueban el programa.</li>
<li><i>COPYRIGHT</i> o <i>LICENCIA</i> menciona las restricciones de copyright. Sin embargo, no hay que poner toda la GPL :).</li>
<li><i>DISPONIBILIDAD</i> anuncia dónde se pueden encontrar versiones más recientes.</li>
<li><i>AUTOR</i> explica quién ha hecho el programa, si no lo hace ya la sección COPYRIGHT.</li>
<li><i>VÉASE TAMBIÉN</i> refiere al lector a un lugar con más documentación.</li>
</ul>
<p>Todos estos son para <tt>=head1</tt>.</p>
<p>Las funciones, métodos y todo eso se explican normalmente en una sección <tt>=head2</tt> bajo DESCRIPCIÓN.</p>
<p>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 <tt>undef</tt> cuando hay errores, hay que hacérselo saber a la gente.</p>
<p>Está bien escribir frases cortas. Es mejor evitar las largas.</p>
<h2>Ejemplos de código</h2>
<p>Los párrafos tabulados se toman como código, con la tabulación intacta. ¡Así de fácil!:</p>
<code>=head1 SINOPSIS
use My::Module;
my $object = My::Module->new();
print $object->as_string;</code>
<p>Esto se llama un <i>párrafo textual</i>.</p>
<h2>Marcado</h2>
<p>POD soporta un pequeño conjunto de elementos de marcado. Para mantener mi promesa, me voy a limitar a enumerarlos:</p>
<ul>
<li><tt>B<texto en negrita></tt></li>
<li><tt>I<texto en cursiva></tt></li>
<li><tt>U<texto subrayado></tt></li>
<li><tt>C<código></tt></li>
<li><tt>B<y se pueden I<anidar>></tt></li>
</ul>
<p>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.</p>
<p>Si alguna vez hace falta incluir un carácter '>' dentro de código, hay dos opciones. Si queremos poner <tt>$foo->bar</tt> con fuente de código, podemos hacer esto:</p>
<ul>
<li><tt>C<$foo-E<gt>bar></tt></li>
<li><tt>C<< $foo->bar >></tt> (¡los espacios son necesarios!)</li>
<li><tt>C<<< $foo->bar >>></tt> (¡los espacios son necesarios!)</li>
</ul>
<h2>Entidades</h2>
<p>Hemos visto que se puede usar E para entidades. Son como las entidades de HTML; también tenemos estas:</p>
<ul>
<li><tt>verbar</tt> para una barra vertical.</li>
<li><tt>sol</tt> para una barra (solidus).</li>
</ul>
<p>Las entidades numéricas pueden ir en decimal, octal (con el prefijo '0') y en hexadecimal (con el prefijo '0x').</p>
<h2>Listas</h2>
<p>En este caso un ejemplo es mucho más claro que una explicación:</p>
<code>=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</code>
<p>Como puede verse, se empieza esta lista con <tt>=over</tt> y la acabamos con <tt>=back</tt>. Entre ambos comandos hay <tt>=item</tt>s. El número después de <tt>=over</tt> 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:</p>
<code> Methods
"new" Returns a new
My::Module object.
"as_string" Returns a stringified
representation of the
object. This is mainly
for debugging purposes.</code>
<h2>Otras cositas de POD</h2>
<p>Se puede usar L para enlazar a secciones del mismo documento o a otros documentos. POD se termina con <tt>=cut</tt> para volver a Perl. Hay comandos especiales para los distintos formatos de salida. Para leer la documentación completa de POD, teclear:</p>
<code>perldoc perlpod</code>
<h2>Un ejemplo completo</h2>
<code>=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</code>
<h2>Conclusión</h2>
<p>Documentar con POD es fácil. ¡A divertirse!</p>