fix from github review - better documentation and clearer method