How can I briefly document methods in Perl code?

Question

I favor the kind of literary style of programming with POD comments next to the code they document. Unfortunately, this inflates code, which is not very Perlish ;-) The best way I could find is to use Dist :: Zilla with Pod :: Weaver :

package Foo; #ABSTRACT: Foobar helper module for Foos =method foo ( $bar, $doz ) Lorem ipsum hopladi and hoplada. =cut sub foo { ... } 

Arguably delete blank lines, but it also reduces readability. Isn't there a way to write more concise without any repetitive and unnecessary syntax:

 package Foo; #ABSTRACT: Foobar helper module for Foos #METHOD: Lorem ipsum hopladi and hoplada. sub foo { # $bar, $doz ... } 

And increase this to a full POD:

 =head1 NAME Foo - Foobar helper module for Foos =head1 METHODS =head2 foo ( $bar, $doz ) Lorem ipsum hopladi and hoplada. 

I think this should be possible with the Pod :: Weaver plugin, but trying to understand the architecture of Pod :: Weaver in combination with Dist :: Zilla and PPI made my brain hurt: - (

Answer 1

I used two different implementations (for Perl projects) Natural documents and OODoc , which are close to your requirements. I do not recommend any of them, simply because I do not like the auto-generated documentation, regardless of language. Good documentation takes time and effort, otherwise you will get a documentation skeleton that is useless.

Answer 2

I'll start with the question, why do you need such brief statements about documentation?

I used Natural Docs and I like it a lot. My documentation style is not concise, but I find it readable. Example:

 =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 

Natural documents can automatically select a function or method name. In addition, I use it to document javascript sources and global documentation and can insert links between them.