Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

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!


In reply to POD en 5 minutos by Hue-Bond

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others chilling in the Monastery: (14)
    As of 2014-07-25 21:15 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      My favorite superfluous repetitious redundant duplicative phrase is:









      Results (175 votes), past polls