POD speculation
[...] expects to find either a
=head(n>1)or an=itemblock documenting a subroutine.
In pure TIMTOWTDI spirit, it's up to you to decide which style you want to adopt. There are PROs and CONs, though.
I have always been skewed on adopting the list-style via =item, because this puts all functions/methods at the same "mental" level of a list. So, I can have a module composed of a few functions only:
=head1 FUNCTIONS
=over
=item B<< some_function >>
=back
living aside with another one where I find it more useful to group functions by semantic, like this:
=head1 METHODS
=head2 Constructors
=over
=item B<< new >>
=item B<< create >>
=back
=head2 Accessors
=over
=item B<< foo >>
You get the idea by now...
It always made me feel uneasy that, in the titles way using =headN, there is no specific nesting level assigned to functions.
It turns out that this is the very Achille's heels of the list approach, though. When the POD is rendered in HTML (as in Pod::Coverage itself, for example!), the auto-generated index at the beginning does not contain a pointer to the functions, which I find extremely useful e.g. as seen in Dancer or Mojolicious. These modules seem to avoid the leveling problem by just promoting the sub-groups at the =head1 level, which is semantically disturbing (for me, because I would tend to group the interface description in a single chapter) but pragmatically OK.
My personal take away is that the title-based approach is superior, and I'll stick to that in the future.
I'm using the title-based approach too, for the same reasons. I've also switched to putting only the function/method name in the title (as it makes the HTML anchor simpler), and putting a code example below in a verbatim block (which gives more room than a single line to show proper usage).
Compare:
- https://metacpan.org/pod/release/BOOK/Git-Repository-1.309/lib/Git/Repository.pm#command-cmd
- https://metacpan.org/pod/Git::Repository#command
Regarding the nesting level, isn't it possible to just use =head3 for the functions/methods themselves? My pod2html renders that fine (so does perldoc).
No one ever reads my doc. Much less the actual pod that generates it. If the topic even comes up it is to defend the use of perl when blub is so much better. Still here are my thoughts:
I'm pretty much a snippet user and use one that maps sub foo into =head3 foo\n\n\n\=cut\n\nsub foo {\n}
The main reason to choose a head over a item is the typesetting tradition of TOC elements for all heads. The choice of =head3 leaves room for a =head2 to provide subsections if needed between the predefined =head1 sections demanded by manual page convention. Of course I did spend quite a bit of time with troff and the -man macros back in the good old days so my fingers may have developed a bias.
Hi Chris,
Makes sense. I always used "=item" because it allowed me to say "=item B<foo> ( [I<arg>] )", but that only gets you so far. It looks nice, but it doesn't show up in the TOC, and worse, for longer lists of methods/functions, I often screw up with the "=over"/"=back" balancing.
I think I'll switch to "=head3" from now on.
And in my case, people do read my doc. Unfortunately, people that then take over maintenance make changes, but neglect to update the doc (including updating the AUTHOR entry, so I get blamed for bad documentation).
Thanks all for the feedback and additional hints. As for me, I don't know if people read my docs (or use my modules at all, apart a few exceptions), but I surely do read them and I find the list of functions/methods in the TOC to be soooo useful!