From e76363c53220a90d41ea989b4cdca46506d881f3 Mon Sep 17 00:00:00 2001
From: Nathan Marz <nathan@nathanmarz.com>
Date: Tue, 7 Jun 2016 10:18:20 -0400
Subject: [PATCH] more docstrings and benchmarks

---
 scripts/benchmarks.clj             | 3 +++
 src/clj/com/rpl/specter.cljx       | 9 +++++++--
 src/clj/com/rpl/specter/macros.clj | 3 ++-
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/scripts/benchmarks.clj b/scripts/benchmarks.clj
index 3537182..2ad07f1 100644
--- a/scripts/benchmarks.clj
+++ b/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)
diff --git a/src/clj/com/rpl/specter.cljx b/src/clj/com/rpl/specter.cljx
index fe9a263..4a2bc92 100644
--- a/src/clj/com/rpl/specter.cljx
+++ b/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)
diff --git a/src/clj/com/rpl/specter/macros.clj b/src/clj/com/rpl/specter/macros.clj
index 9c289ea..23ad7f2 100644
--- a/src/clj/com/rpl/specter/macros.clj
+++ b/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."