[...] expects to find either a
=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.