more docstrings and benchmarks

scripts/benchmarks.clj

@@ -56,6 +56,9 @@
       p (comp-paths :a :b :c)]
   (run-benchmark "get value in nested map" 10000000
     (select-any [:a :b :c] data)
+    (select-one [:a :b :c] data)
+    (select-first [:a :b :c] data)
+    (select-one! [:a :b :c] data)
     (compiled-select-any p data)
     (get-in data [:a :b :c])
     (-> data :a :b :c)

src/clj/com/rpl/specter.cljx

@@ -91,7 +91,8 @@
   NONE i/NONE)
 
 (defn select-any*
-  "Returns any element found or [[NONE]] if nothing selected."
+  "Returns any element found or [[NONE]] if nothing selected. This is the most
+   efficient of the various selection operations."
   [path structure]
   (compiled-select-any (i/comp-paths* path) structure))
 
@@ -177,7 +178,11 @@
   ALL
   (comp-paths (i/->AllNavigator)))
 
-(defnav MAP-VALS []
+(defnav
+  ^{:doc "Navigate to each value of the map. This is more efficient than 
+          navigating via [ALL LAST]"}
+  MAP-VALS
+  []
   (select* [this structure next-fn]
     (doseqres NONE [v (vals structure)]
       (next-fn v)

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

@@ -566,7 +566,8 @@
   `(i/compiled-select-first* (path ~apath) ~structure))
 
 (defmacro select-any
-  "Returns any element found or [[NONE]] if nothing selected.
+  "Returns any element found or [[NONE]] if nothing selected. This is the most
+   efficient of the various selection operations.
    This macro will attempt to do inline factoring and caching of the path, falling
    back to compiling the path on every invocation it it's not possible to 
    factor/cache the path."