     (.stop (component) (name cache-or-name))))
 
 (defn builder
-  "For advanced use, call this function to obtain a fluent Infinispan
-  configuration builder. Set the desired options, and invoke its build
-  method, the result from which can be passed in the :configuration
-  option of the cache function."
+  "For advanced use, call this function to obtain a \"fluent
+  Infinispan configuration builder\". Set the desired options, and
+  invoke its build method, the result from which can be passed in the
+  :configuration option of the {{cache}} function. For example:
+
+  ```
+  (let [config (.. (builder :ttl [30 :minutes])
+                  clustering l1 (enabled true) build)]
+    (cache \"L1\" :configuration config))
+  ```
+
+  Note that builder takes the same options as {{cache}} so you can
+  concisely initialize it with Clojure, and use Java interop to set
+  the more esoteric options"
   [& options]
   (Config/builder (-> options
                     kwargs-or-map->map

(set-valid-options! cache (opts->set Caching$CreateOption))

(defn with-codec
  "Returns a cache that stores/retrieves entries in the passed cache
  using the passed codec. The default is `:none` but the following are
  supported: `:edn`, `:json`, and `:fressian`. To use the latter two,
  the `cheshire` and `org.clojure/data.fressian` libraries,
  respectively, must be available on the classpath."
  [cache codec]
  (.encodedWith (component)
    (lookup-codec codec)

   singular and plural versions of :second, :minute, :hour, :day, and
   :week are valid period keywords.

   * :ttl - the max time the entry will live before expiry [-1]
   * :idle - the time after which an entry will expire if not accessed [-1]

   Replication: the replication mode defaults to :dist-sync when
   clustered. When not clustered, the value of :mode is ignored, and
   the cache will be :local. Asynchronous replication may yield a
   slight performance increase at the risk of potential cache
   inconsistency.

   * :mode - replication mode [:dist-sync or :local] one of :local,
             :repl-sync, :repl-async, :invalidation-sync,
             :invalidation-async, :dist-sync, :dist-async

   Transactions: caches can participate in transactions when a
   TransactionManager is available.

   * :transactional - whether the cache is transactional [false]
   * :locking - transactional locking schemes [:optimistic]
                one of :optimisitic or :pessimistic

   Advanced configuration: the options listed above are the most
   commonly configured, but Infinispan has many more buttons,
   switches, dials, knobs and levers. Call the {{builder}} function to
   create your own Configuration instance and pass it in via the
   :configuration option.

   * :configuration - an org.infinispan.configuration.cache.Configuration instance"
  ([name]
    (cache name {}))
  ([name k v & kvs]
