add doc for must-cache-paths

CHANGES.md

@@ -4,7 +4,7 @@
 * BREAKING CHANGE: fixed-pathed-path and variable-pathed-path renamed to fixed-pathed-nav and variabled-pathed-nav
 * New `path` macro does intelligent inline caching of the provided path. The path is factored into a static portion and into params which may change on each usage of the path (e.g. local parameters). The static part is factored and compiled on the first run-through, and then re-used for all subsequent invocations. As an example, `[ALL (keypath k)]` is factored into `[ALL keypath]`, which is compiled and cached, and `[k]`, which is provided on each execution. If it is not possible to precompile the path (e.g. [ALL some-local-variable]), nothing is cached and the path will be compiled on each run-through.
 * Added `must-cache-paths!` function to throw an error if it is not possible to factor a path into a static portion and dynamic parameters.
-* BREAKING CHANGE: all select/transform/setval/replace-in functions changed to macros and moved to com.rpl.specter.macros namespace. The new macros now automatically wrap the provided path in `path` to enable inline caching. Expect upwards of a 100x performance improvement without using explicit precompilation, and to be within 2% to 15% of the performance of explicitly precompiled usage.
+* BREAKING CHANGE: all select/transform/setval/replace-in functions changed to macros and moved to com.rpl.specter.macros namespace. The new macros now automatically wrap the provided path in `path` to enable inline caching. Expect up to a 100x performance improvement without using explicit precompilation, and to be within 2% to 15% of the performance of explicitly precompiled usage.
 * Added select*/transform*/setval*/replace-in*/etc. functions that have the same functionality as the old select/transform/setval/replace-in functions.
 * Added `must` navigator to navigate to a key if and only if it exists in the structure
 * Added `ATOM` navigator (thanks @rakeshp)

src/clj/com/rpl/specter.cljx

@@ -26,7 +26,17 @@
 (defn comp-paths [& paths]
   (i/comp-paths* (vec paths)))
 
-(def must-cache-paths! i/must-cache-paths!)
+(def ^{:doc "Mandate that operations that do inline path factoring and compilation
+             (select/transform/setval/replace-in/path/etc.) must succeed in 
+             factoring the path into static and dynamic portions. If not, an
+             error will be thrown and the reasons for not being able to factor
+             will be printed. Defaults to false, and `(must-cache-paths! false)`
+             can be used to turn this feature off.
+
+             Reasons why it may not be able to factor a path include using
+             a local symbol, special form, or regular function invocation
+             where a navigator is expected."}
+  must-cache-paths! i/must-cache-paths!)
 
 ;; Selection functions
 

src/clj/com/rpl/specter/macros.clj

@@ -404,8 +404,7 @@
     `(let [info# (i/get-path-cache ~cache-id)
            
            ^com.rpl.specter.impl.CachedPathInfo info#
-            (if (some? info#)
-              info#
+            (if (nil? info#)
               (let [info# (i/magic-precompilation
                            ~prepared-path
                            (quote ~used-locals)
@@ -415,7 +414,9 @@
                            )]
                 (i/add-path-cache! ~cache-id info#)
                 info#
-                ))
+                )
+              info#
+              )
 
            ~precompiled-sym (.-precompiled info#)
            ~params-maker-sym (.-params-maker info#)]