Perl kodunda yöntemleri nasıl belgeleyebilirim?

Question

Belgelere ekledikleri kodun yanında POD yorumlarıyla bir çeşit edebi programlama stilini tercih ediyorum.

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

biri boş satırları kaldırmak için öne sürülebilir ancak bu da okunabilirliği azaltır: Ne yazık ki bu çok Perlish değil kod, bloats ;-) Şimdiye kadar bulabildiğim en iyi yolu böyle Pod::Weaver ile Dist::Zilla kullanmaktır .

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

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

Ve bu tam POD genişletilmiş olsun: Ben bir Pod ile muhtemelen gerektiğini düşünüyorum

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

bu gibi herhangi bir yinelenen ve gereksiz sözdizimi olmadan daha özlü yazmak için bir yol yok :: Weaver eklentisi, Pod :: Weaver'ın mimarisini anlamaya çalışırken Dist :: Zilla ve PPI ile kombine edilmiş beyin beynim zarar verdi :-(

Answer 1

İki farklı uygulama (Perl projeleri için) kullanıyorum Natural Docs ve OODoc senin rına yakın equirement. Bunlardan hiçbirini tavsiye etmiyorum, çünkü dilden bağımsız olarak otomatikleştirilmiş belgeleri sevmem. İyi belgeler zaman ve çaba gerektirir, aksi takdirde işe yaramaz bir belge iskeleti ile sonuçlanırsınız.

Answer 2

Neden bu kadar kısa dökümantasyon dökümanlarına ihtiyacınız olduğunu sorarak başlayacağım.

Doğal Belgeler'i kullandım ve bunu gerçekten çok seviyorum. Belge tarzım özlü değil ama okunabilir olduğunu buldum. Örnek:

=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 

Doğal Dokümanlar otomatik olarak işlev veya yöntem adı almak edebilmektedir. Ayrıca javascript kaynaklarımı ve genel belgeleri belgelemek için kullanıyorum ve aralarında çapraz bağlantılar ekleyebilirim.