too much commenting for your taste?

Yup. :-)

The NAME section is entirely redundant; you can safely get away without telling the reader that a routine declared as sub dump_subtable is called "dump_subtable" and dumps a subtable. As for the rest, well, it depends. If this is an interface function, then spelling out the options, listing bugs, and providing several examples is good and useful, but should probably be POD rather than comments. If it's a utility function that doesn't get exported, then IMO you'd probably be better off with a small comment block at the top, and maybe some useful comments inline.

--
The hell with paco, vote for Erudil!
/msg me if you downvote this node, please.
:wq