Coming across this rather late, all I can say is that my script template would use Pod::Usage and Getopt::Long and do all the documentation in pod rather than comments.

Hope this is still of some use :)