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
[download]

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
[download]

Here's an example that contains a bit of both of the above.