cache: improve documentation for public and internal APIs
Authored by: cboos 2011-02-22
Parent: [r10584]
Child: [r10586]