in reply to Recommended subroutine documentation style

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?