Docs on resolver are out of date

[samskiter]

Does not check the store first, but stores the retrieved document in the store if :attr:RefResolver.cache_remote is True.

In fact, by the time this has been called, the store has already been checked.

To help anyone out here, our approach is to make 1 resolver for the whole app and pass the constructor an empty string and none for the first two args and then hand it a handler. like so:

resolver = jsonschema.RefResolver("", None)

This resolver will then fetch and cache any schema that are ref'd. If we share this instance of resolver across all our validate calls when we will share the cache too.

[Julian]

Hm, if I understand what you mean, this is correct, but obviously confusing. It's true, that method (which is public, and callable), does not check the store. Validators, when using ref resolvers though, go via a path that will check the store and then call that method, but that docstring is documentation for that particular method. Suggestions welcome on how to clarify that.

[samskiter]

I think the confusion arose from reading the docs here:

http://python-jsonschema.readthedocs.org/en/latest/references/

I wasn't sure whether the intention was to overload that method to resolve remotes locally. (in fact the way to do this is to use a handler or init with a dict).

Maybe just remove the reference to the store. Or maybe bundle the store check into this method so it does everything related to resolving a remote ref? (where "remote" means: "not in this current schema file")

[Julian]

There's definitely a need for some clearer ref docs -- I've very slightly clarified the wording here, but hopefully once we have those stuff like this will be a bit clearer.