add docstrings for new API elements

scripts/benchmarks.clj

@@ -95,6 +95,12 @@
     (select-any (filterer even?) data)
     ))
 
+(let [data [{:a 2 :b 2} {:a 1} {:a 4} {:a 6}]]
+  (run-benchmark "even :a values from sequence of maps" 1000000
+    (select [ALL :a even?] data)
+    (->> data (mapv :a) (filter even?) doall)
+    ))
+
 
 (defn- update-pair [[k v]]
   [k (inc v)])

src/clj/com/rpl/specter.cljx

@@ -86,10 +86,12 @@
 (def ^{:doc "Version of select-any that takes in a path pre-compiled with comp-paths"}
   compiled-select-any i/compiled-select-any*)
 
-(def NONE i/NONE)
+(def ^{:doc "Global value used to indicate no elements selected during
+             [[select-any]]."}
+  NONE i/NONE)
 
 (defn select-any*
-  "Returns any element found."
+  "Returns any element found or [[NONE]] if nothing selected."
   [path structure]
   (compiled-select-any (i/comp-paths* path) structure))
 

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

@@ -566,7 +566,7 @@
   `(i/compiled-select-first* (path ~apath) ~structure))
 
 (defmacro select-any
-  "Returns first element found.
+  "Returns any element found or [[NONE]] if nothing selected.
    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."