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 :-(

score 3 · Answer 1 · answered Aug 28 '12 at 21:29

3

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.

answered Aug 28 '12 at 21:29

chansen

2,446
15
20

Thanks. I'd distinguish documentation in form of explanations and examples (which are usually found in the `DESCRIPTION` and `SYNOPSIS` section in Perl) and documentation of method purpose and calling syntax. The former is essential for good documentation, the latter is just convenient and it can be auto-generated very well. – Jakob Aug 29 '12 at 07:17

score 1 · Answer 2 · edited Sep 03 '12 at 14:12

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.

If I document a method in much detail, the brevity does not matter, but in some cases one sentence and a list of parameters is enough. I only ask for this case. — Jakob, Sep 03 '12 at 14:17

How can I concisely document methods in Perl code?

2 Answers2