Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

Guidelines for listing functions/methods in POD?

by Dallaylaen (Friar)
on Dec 07, 2017 at 20:34 UTC ( #1205110=perlquestion: print w/replies, xml ) 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

=head2 frobnicate =over =item frobnicate( $foo, $bar ) =item frobnicate( \%baz ) =back

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!

Replies are listed 'Best First'.
Re: Guidelines for listing functions/methods in POD?
by Your Mother (Chancellor) on Dec 07, 2017 at 21:33 UTC

    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.

Re: Guidelines for listing functions/methods in POD?
by kcott (Chancellor) on Dec 08, 2017 at 07:22 UTC

    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 ...

    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.

    — Ken

Re: Guidelines for listing functions/methods in POD?
by LanX (Bishop) on Dec 07, 2017 at 21:05 UTC

      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

Re: Guidelines for listing functions/methods in POD?
by stevieb (Abbot) on Dec 08, 2017 at 00:33 UTC

    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

    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

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

Re: Guidelines for listing functions/methods in POD?
by BillKSmith (Vicar) on Dec 07, 2017 at 22:11 UTC
    If you prepare your modules with the utility module-starter it will prepare an outline of your module including the pod to create conventional man pages.
    Bill
Re: Guidelines for listing functions/methods in POD?
by Anonymous Monk on Dec 07, 2017 at 23:24 UTC
    Do this
    =head2 frobnicate =head2 frobnicate( $foo, $bar ) =head2 frobnicate( \%baz ) =cut

      i forgot code tags

      =head2 c<<< $moo->frobnicate >>>

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1205110]
Front-paged by haukex
help
Chatterbox?
and one hand claps...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (10)
As of 2017-12-18 13:27 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What programming language do you hate the most?




















    Results (485 votes). Check out past polls.

    Notices?