improve documentation and fix up perl critic complaints