Perlコードでメソッドを簡潔に記述するにはどうすればよいですか？

Question

私はPODコメントが書かれているコードの隣に、一種のリテラルプログラミングスタイルを好みます。

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

=method foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

=cut 

sub foo { 
    ... 
} 

一つの空行を削除するために主張することができますが、これはまた、可読性を低下させる：残念ながら、これは非常にPerl的でないコードは、bloats ;-)私は今では見つけることができる最良の方法は、そのようなPod::WeaverでDist::Zillaを使用することです。

package Foo; 
#ABSTRACT: Foobar helper module for Foos 

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

そして、これは完全なPODに展開されます：私はそれがポッドで、おそらくされるべきだと思う

=head1 NAME 

Foo - Foobar helper module for Foos 

=head1 METHODS 

=head2 foo ($bar, $doz) 

Lorem ipsum hopladi and hoplada. 

このような任意の繰り返し、不必要な構文のない、より簡潔な記述にする方法はありません:: Weaverプラグインが、Dist :: ZillaとPPIのアーキテクチャーを理解しようとすると、私の脳が痛くなりました:-(

Answer 1

私は2つの異なる実装（Perlプロジェクト用）Natural DocsとOODocあなたのrに近い等価。言語に関係なく自動生成されたドキュメントが好きではないため、私はそれらのいずれもお勧めしません。良いドキュメントには時間と労力が必要です。そうでなければ、役に立たないドキュメントの骨組みになります。

Answer 2

私は、なぜ簡潔な文書を必要としているのか尋ねることから始めますか？

私はNatural Docsを使用しています。本当に好きです。 私の書類のスタイルは簡潔ではありませんが、わかりやすいものです。 例：

=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 

自然ドキュメントは、自動的に関数やメソッド名を選択することができます。 さらに、私は自分のjavascriptソースとグローバルドキュメントを文書化するためにそれを使用し、それらの間にクロスリンクを挿入することができます。