From d9443232d864dd192e2a287831d7bc7def513387 Mon Sep 17 00:00:00 2001
From: Nathan Marz <nathan@nathanmarz.com>
Date: Sat, 4 Jun 2016 09:29:45 -0400
Subject: [PATCH] add docstrings to the core select/transform/etc. macros

---
 src/clj/com/rpl/specter.cljx       |  2 +-
 src/clj/com/rpl/specter/macros.clj | 51 ++++++++++++++++++++++++++----
 2 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/src/clj/com/rpl/specter.cljx b/src/clj/com/rpl/specter.cljx
index 8d66c0f..d8dbd51 100644
--- a/src/clj/com/rpl/specter.cljx
+++ b/src/clj/com/rpl/specter.cljx
@@ -40,7 +40,7 @@
 
 ;; Selection functions
 
-(def ^{:doc "Version of select that takes in a path pre-compiled with comp-paths"}
+(def ^{:doc "Version of select that takes in a path precompiled with comp-paths"}
   compiled-select i/compiled-select*)
 
 (defn select*
diff --git a/src/clj/com/rpl/specter/macros.clj b/src/clj/com/rpl/specter/macros.clj
index 35e4213..41b9724 100644
--- a/src/clj/com/rpl/specter/macros.clj
+++ b/src/clj/com/rpl/specter/macros.clj
@@ -496,25 +496,64 @@
          ))
   ))
 
-(defmacro select [apath structure]
+(defmacro select
+  "Navigates to and returns a sequence of all the elements specified by the path.
+   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."
+  [apath structure]
   `(i/compiled-select* (path ~apath) ~structure))
 
-(defmacro select-one! [apath structure]
+(defmacro select-one!
+  "Returns exactly one element, throws exception if zero or multiple elements found.
+   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."
+  [apath structure]
   `(i/compiled-select-one!* (path ~apath) ~structure))
 
-(defmacro select-one [apath structure]
+(defmacro select-one
+  "Like select, but returns either one element or nil. Throws exception if multiple elements found.
+   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."
+  [apath structure]
   `(i/compiled-select-one* (path ~apath) ~structure))
 
-(defmacro select-first [apath structure]
+(defmacro select-first
+  "Returns first element found. Not any more efficient than select, just a convenience.
+   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."
+  [apath structure]
   `(i/compiled-select-first* (path ~apath) ~structure))
 
-(defmacro transform [apath transform-fn structure]
+(defmacro transform
+  "Navigates to each value specified by the path and replaces it by the result of running
+   the transform-fn on it.
+   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."
+  [apath transform-fn structure]
   `(i/compiled-transform* (path ~apath) ~transform-fn ~structure))
 
-(defmacro setval [apath aval structure]
+(defmacro setval
+  "Navigates to each value specified by the path and replaces it by `aval`.
+   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."
+  [apath aval structure]
   `(i/compiled-setval* (path ~apath) ~aval ~structure))
 
 (defmacro replace-in
+  "Similar to transform, except returns a pair of [transformed-structure sequence-of-user-ret].
+   The transform-fn in this case is expected to return [ret user-ret]. ret is
+   what's used to transform the data structure, while user-ret will be added to the user-ret sequence
+   in the final return. replace-in is useful for situations where you need to know the specific values
+   of what was transformed in the data structure.
+   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."
   [apath transform-fn structure & args]
   `(i/compiled-replace-in* (path ~apath) ~transform-fn ~structure ~@args))