Improve caching documentation.

It was a little weak, and folk need enough detail to reason about
performance.

Change-Id: I67f81ab5a206b3d42dd1e4e1eb52af88ac1a3adc