update 'out' docs for caching and add 'in' section