Add package-info javadocs for the page cache API

Also notes a couple of TODOs for future test work that needs to be done,
and a change to the behaviour when running out of storage space.