tidy up inline documentation and clarify $ variable