Fixed #16785 -- Documented some of the design decisions of the cache framework.

Thanks jamesp for the draft patch.