How can I concisely document methods in Perl code?

Question

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

package Foo;
#ABSTRACT: Foobar helper module for Foos

=method foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

=cut

sub foo {
   ...
}

One could argue to remove empty lines but this also decreases readability. Isn't there a way to write more concise without any repeating and unnecessary syntax like this:

package Foo;
#ABSTRACT: Foobar helper module for Foos

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

And get this expanded to full POD:

=head1 NAME 

Foo - Foobar helper module for Foos

=head1 METHODS

=head2 foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

I think it should be possibly with a Pod::Weaver plugin but trying to understand the architecture of Pod::Weaver combined with Dist::Zilla and PPI made my brain hurt :-(

Answer 1

I will start by asking why do you need so concise documentation statements?

I have used Natural Docs, and I really like it. My style of documentation 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 Docs is able to automatically pick the function or method name. Moreover I use it to document my javascript sources and global documentation, and can insert cross-links between them.

Answer 2

I have used two different implementations (for Perl projects) Natural Docs and OODoc that are close to your requirement. I do not recommend any of them, simply because I don't like autogenerated documentation regardless of language. Good documentation requires time and efforts, otherwise you end up with a skeleton of documentation that is useless.