satisfy perlcritic
fix handling of args and return values
tidy up code
documentation
tidy up testfile