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?
