Recommended subroutine documentation style

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.	[reply]
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; } [download] I haven't been using POD for very long though so maybe others have some more POD specific ideas?	[reply] [d/l]