Come posso documentare in modo conciso i metodi nel codice Perl?

Question

Preferisco un tipo di stile di programmazione letterale con i commenti POD accanto al codice che documentano. Purtroppo questo contribuisce ad appesantire il codice, che non è molto la Perl ;-) Il modo migliore che ho trovato per ora è quello di utilizzare Dist::Zilla con Pod::Weaver così:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

si potrebbe sostenere per rimuovere le linee vuote, ma questo diminuisce anche la leggibilità . Non c'è un modo per scrivere più conciso, senza alcuna sintassi ripetitiva e inutile come questo:

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

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

e ottenere questo estesa a pieno POD:

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

penso che dovrebbe essere possibilmente con un baccello :: Il plugin Weaver, ma cercando di capire l'architettura di Pod :: Weaver combinato con Dist :: Zilla e PPI mi ha fatto male al cervello :-(

Answer 1

Ho usato due diverse implementazioni (per progetti Perl) Natural Docs e OODoc che sono vicino al tuo r equirement. Non ne raccomando nessuno, semplicemente perché non mi piace la documentazione autogenerata indipendentemente dalla lingua. Una buona documentazione richiede tempo e sforzi, altrimenti si finisce con uno scheletro di documentazione che è inutile.

Answer 2

Inizierò chiedendo perché avete bisogno di dichiarazioni di documentazione così concise?

Ho usato Natural Docs e mi piace molto. Il mio stile di documentazione non è conciso, ma lo trovo leggibile. Esempio:

=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 

naturale Docs è in grado di selezionare automaticamente il nome della funzione o del metodo. Inoltre lo uso per documentare i miei sorgenti javascript e la documentazione globale, e posso inserire collegamenti incrociati tra loro.