Docs for core.cache.documentation are ambigous

Question

The doc example on https://cljdoc.org/d/org.clojure/core.cache/1.0.225/doc/using-core-cache does not mention that one has to choose between core.cache and core.cache.wrapped More specifically, when creating the cache, the example has imported the core.cache namespace. However later on, when coming to lookup-or-miss, core.cache.wrapped is assumed to be imported. When one tries to use wrapped/lookup-or-miss with a cache created from the factory in core.cache, one encounters the rather ambigous expection:

class clojure.core.cache.LRUCache cannot be cast to class clojure.lang.IAtom

I think providing more complete examples in the docs would aleviate this issue.

Answer 1

Thank you for the feedback! Since I took over maintenance of core.cache I will admit that I have not spent a lot of time on the docs. Given the Clojurists Together funding for 2023, I'll set aside some time to completely overhaul the docs for this library.

We use clojure.core.cache.wrapped extensively at work, because it is so much more convenient than trying to work with clojure.core.cache and managing the atoms etc yourself. I need to distil that experience and make sure the docs reflect that.

Comments

Sean,

Happy to read over anything that you write and help in any other way possible.

---

I've added some notes to the README (and to a couple of the /docs pages in the repo) to try to clarify the two styles of usage: https://github.com/clojure/core.cache/blob/master/README.md

In particular, I changed the :as alias for clojure.core.cache.wrapped to w (from c) so it's clearer that the second block of examples all uses the wrapped API.