fixed caching bug and related issues

That doesn't really say what this function does -- what sort of thing will it give you?  Are there any guarantees about the order or type, etc. of the data returned?  Are there any prerequisites?  We need to say what a user of this method would need to know, along with what the author of a subclass would need, especially about what we expect and what we promise.