Documentation for 'cached' is on its way. There'll be a blog post up soon with a friendly introduction, and some representative benchmarks. In the meantime there's a drier but more detailed specification of the behaviour of 'cached' waiting in a pull request here:
