added with-inline-debug helper and updated comment on dynamicnavs

src/clj/com/rpl/specter/impl.cljc

@@ -776,13 +776,15 @@
      form)
     (get-cell used-locals-cell)))
 
+(def ^:dynamic *DEBUG-INLINE-CACHING* false)
+
 (defn magic-precompilation [path ns-str used-locals-list]
 ;  (println "before magic-precompilation*:" path)
   (let [used-locals-set (set used-locals-list)
-        path (magic-precompilation* path)
+        magic-path (magic-precompilation* path)
 ;        _ (println "magic-precompilation*" path)
         ns (find-ns (symbol ns-str))
-        final-code (resolve-magic-code (->DynamicPath path))
+        final-code (resolve-magic-code (->DynamicPath magic-path))
         ;; this handles the case where a dynamicnav ignores a dynamic arg and produces
         ;; something static instead
         static? (empty? (used-locals used-locals-set final-code))
@@ -791,6 +793,12 @@
 ;                 (spy
                   `(fn [~@(if static? [] used-locals-list)]
                      ~final-code)))]
+    (when *DEBUG-INLINE-CACHING*
+      (println "Inline caching debug information")
+      (println "--------------------------------")
+      (println "Input path:" path "\n")
+      (println "Processed path:" magic-path "\n")
+      (println "Produced code:" final-code))
     (if static?
       (->CachedPathInfo false (maker))
       (->CachedPathInfo true maker))))

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

@@ -79,6 +79,9 @@
 (defmacro late-bound-richnav [bindings & impls]
   (late-bound-operation bindings `richnav impls))
 
+(defmacro with-inline-debug [& body]
+  `(binding [i/*DEBUG-INLINE-CACHING* true]
+     ~@body))
 
 (defmacro declarepath [name]
   `(def ~name (i/local-declarepath)))
@@ -127,11 +130,11 @@
   `(vary-meta (fn ~@args) assoc :dynamicnav true))
 
 (defmacro defdynamicnav
-  "Defines a higher order navigator that itself takes in one or more paths
-  as input. When inline caching is applied to a path containing
-  one of these higher order navigators, it will apply inline caching and
-  compilation to the subpaths as well. Use ^:notpath metadata on arguments
-  to indicate non-path arguments that should not be compiled"
+  "Defines a function that can choose what navigator to use at runtime based on
+   the dynamic context. The arguments will either be static values or
+   objects satisfying `dynamic-param?`. Use `late-bound-nav` to produce a runtime
+   navigator that uses the values of the dynamic params. See `selected?` for
+   an illustrative example of dynamic navs."
   [name & args]
   (let [[name args] (name-with-attributes name args)]
     `(def ~name (dynamicnav ~@args))))