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.