The major reason the =head2 style came into vogue, you probably had it recommended to you at some point, is that it gives navigation entries on the CPAN sites for documentation page. So, you can click down to a method easily from the top. I disagree that POD semantics should be disregarded and assert that doing it with =item and such is proper. The fault, to me, lies in the presentation layer (CPAN view), not the data (the POD).

Up to you which is right for you.

Pod semantics arent being disregarded.

I was arguing the semantics are being misused. If you have head1, head2, head3... they correspond to something like book, chapter, verse. A single method or function, to me, never rises to the level of chapter. Item is a much better library match for a function than head2. It's a FOSS world, lots of hackers disagree, do what you like, etc. Promoting list items to chapter titles breaks reasonable semantics in my view and promotes lousy hierarchies and slap-dash documentation. But I will cogitate on your thorough and incisive rebuttal since it contains so much to consider.

G'day Dallaylaen,

These are just my thoughts and personal preferences on the subject. I don't even present these as recommended guidelines. It's entirely your choice whether you wish to implement any of these ideas.

I do like to see function names in the index because it aids page navigation. I only want to see the function name appearing once in the index; not multiple entries with every variation of the argument list.

I prefer to add function names alphabetically; again, for ease of navigation. I would normally add a function name at the =head2 level. With a large number of functions which, perhaps, fall into some natural grouping, I might use =head2 for group names and =head3 for the function names. Whether or not I decide groupings are needed, I'll generally aim for all functions to be at the same =headN level.

Here's how I might present a function with a variable argument list:

=head2 function

C<function> can take various arguments as follows.

    $retval = function();
    $retval = function($arg);
    $retval = function($arg, \%arg_map);
    $retval = function($arg, \%arg_map, \@arg_list);

The arguments are:

=over 4

=item C<$arg>

A string denoting ...

The default is ...

=item C<%arg_map>

This is a hash of ...

...

=back

Missing arguments use the defaults shown.

The return value (C<$retval>) is always ...
[download]

Obviously, that's just a very sketchy outline. Meaningful names for variables, even in documentation, greatly aid comprehension. And, of course, when I come back to this in six months, there should be sufficient information for me to use function(...) without having to search through the source code: if it doesn't do that for me, it won't do it for others, and I've just wasted my time bothering to pretend to provide documentation.

I've read through perlmodstyle and such, as well as some old posts on the internet including one with a link to Perl Best Practices. None satisfied me, and I don't have PBP, which is a shame I have to live with.

Also this very post was first hit by the time I followed your link :)

> Also this very post was first hit by the time I followed your link :)

Surprising, I just copied your title and added "Perl" :)

Cheers Rolf
_{(addicted to the Perl Programming Language and ☆☆☆☆ :)
Wikisyntax for the Monastery}

I've been doing this (untested):

=head1 METHODS

=head2 blah

Does something or other, all params are passed in as a hash.

Parameters:

    one => $str

Mandatory, String: Parameter that does X.

    two => $bool

Optional, Bool: Does something else
[download]

For functions/methods that take positional parameters (because they aren't many), I often:

=head1 FUNCTIONS

=head2 foo($bar, \@$baz)

I don't know what this function does.

Parameters:

    $bar

Mandatory, Integer: This param enables verbosity. Values: 0-255

    \@baz

Optional, Array reference of Integers: Used to generate a grid size.

Returns: A grid of something as an array reference
[download]

Here's an example that contains a bit of both of the above.

=head2 frobnicate

=head2 frobnicate( $foo, $bar )

=head2 frobnicate( \%baz )

=cut
[download]

i forgot code tags

 
=head2 c<<<    $moo->frobnicate    >>>
[download]