Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

Recommended subroutine documentation style

by markjugg (Curate)
on Aug 27, 2000 at 20:24 UTC ( #29905=perlquestion: print w/replies, xml ) Need Help??

markjugg has asked for the wisdom of the Perl Monks concerning the following question:

Hello Monks, I'm looking for a clean and compact style to document a subroutine interface with using POD. It needs to list out all the different possible input parameters, whether they are positional (like an array) or named (like a hash), what the possible values for each are, whether they are required or not, and what the default values are, if any. It also needs to explain possible return values.

Please provide a quick example of your preferred style, or give a pointer to a module that has a documentation style you think is compact and effective.

Thanks!

-mark

  • Comment on Recommended subroutine documentation style

Replies are listed 'Best First'.
RE: Recommended subroutine documentation style
by gumpu (Friar) on Aug 27, 2000 at 21:13 UTC

    Maybe not quite POD, but you might want to look at this and this for some ideas.

    Have Fun.

Re: Recommended subroutine documentation style
by ncw (Friar) on Aug 28, 2000 at 13:49 UTC
    I'd prefer to keep it compact and terse, on two lines called Input: and Output: (note that POD needs a blank line between them). If two lines aren't enough then use one line per variable

    I also like to write the POD for a function above the function - not at the end of the file. This is slightly awkward to do with POD though (all those blank lines around the =cut etc), but it looks like this :-

    ############################################################ =item daft_function() This is a daft function. Write general stuff about it here. Input: @daft, [ $DEBUG ] Output: { FAILED => <0|1>, ANSWER => <string> } or maybe if you want a bit more description Input: @daft - array of useless items $DEBUG - optional paramter to give daft verbiage Output: Reference to an anonymous hash with these keys FAILED => 0 or 1 ANSWER => string - result of dafting the input =cut ############################################################ sub daft_function { my ($self, @daft) = @_; #... return $result; }
    I haven't been using POD for very long though so maybe others have some more POD specific ideas?

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://29905]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (5)
As of 2021-01-26 22:51 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?