¿Cómo puedo documentar los métodos concisamente en el código Perl?

Question

Estoy a favor de un tipo de estilo de programación literal con comentarios POD junto al código que documentan. Por desgracia, este hincha el código, lo cual no es muy Perlish ;-) La mejor manera que pude encontrar por ahora es utilizar Dist::Zilla con Pod::Weaver así:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

Se podría argumentar para eliminar las líneas vacías, pero esto también disminuye la legibilidad . ¿No hay una manera de escribir más concisa sin ninguna sintaxis repetitiva e innecesaria como esto:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

#METHOD: Lorem ipsum hopladi and hoplada. 
sub foo { # $bar, $doz 
    ... 
} 

Y conseguir esto se expandió a plena POD:

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

creo que debería ser, posiblemente, con una vaina :: Plugin de Weaver, pero tratando de entender la arquitectura de Pod :: Weaver combinado con Dist :: Zilla y PPI hizo daño a mi cerebro :-(

Answer 1

He utilizado dos implementaciones diferentes (para proyectos Perl) Natural Docs y OODoc que son cerca de tu r equirement. No recomiendo ninguno de ellos, simplemente porque no me gusta la documentación autogenerada, independientemente del idioma. Una buena documentación requiere tiempo y esfuerzo, de lo contrario terminará con un esqueleto de documentación que es inútil.

Answer 2

Comenzaré preguntando por qué necesita declaraciones de documentación tan concisas?

He usado Natural Docs, y realmente me gusta. Mi estilo de documentación no es conciso pero me parece legible. Ejemplo:

=begin nd 

Check if a document name is available. 

A name is available iff the name is not used by any other document related to the same study 
excepted if it is another version of the same document. 

Params: 
    name  - Proposed document name to be checked : Str. 
    study  - the study related to the document 
    parent  - parent document or undef if none : <Document> 
    current_instance - the curretn document instance in case of an update 


Returns: 
    true iff the proposed name is valid 

Exception: 
    Dies on bad args or errors. 

=cut 

Docs natural es capaz de recoger automáticamente el nombre de la función o método. Además lo uso para documentar mis fuentes de JavaScript y documentación global, y puedo insertar enlaces cruzados entre ellos.