update documentation to be clear about argument passing