|go ahead... be a heretic|
Guidelines for listing functions/methods in POD?by Dallaylaen (Hermit)
|on Dec 07, 2017 at 20:34 UTC||Need Help??|
Dallaylaen has asked for the
wisdom of the Perl Monks concerning the following question:
Hello dear esteemed monks,
Having published some modules, I finally started wondering about formatting function names
For some reason, cannot even recall why, I began documenting my modules' functions using a header with usage example:=head2 frobnicate( $foo, $bar )
Now it looks rather cumbersome to me, so I'm leaning towards
But I see that many CPAN authors go even further and remove functions/methods from index altogether, leaving only=item frobnicate()
I for one prefer more structured documentation. Where can I find guidelines for doing it properly? What are the reasons for and against each practice? At least Test::Pod::Coverage permits all three...
Oh, it looks like I'm sold on the second variant: after re-reading perldoc perlpod it turns out that sections are linkable via L<Foo::Bar/frobnicate>. Still posting this, there sure is something to add to my thoughts!