docs: zip API docstrings are now clearer about coercion

For regular whitespace-smart operations:
  - consistently using parameter name `item`
    (replace fn was using `value`)
  - now expressly stating we do coercion on `item`

For raw * operations:
  - parameter `item` is now described as "node `item`" to more clearly
    distinguish it from `item` above. I would have preferred naming
    the parameter `node`, but that would be in conflict/confusion
    with the `node` fn.
  - now expressly stating we do no coercion

Closes #168

Author: lread

CHANGELOG.adoc

@@ -16,7 +16,9 @@ For a list of breaking changes see link:#v1-breaking[breaking changes].
 
 === Unreleased
 
-* docs: user guide correction, thanks @rgkirch!
+* docs:
+** user guide correction, thanks @rgkirch!
+** zip API docstrings now clearer about coercion https://github.com/clj-commons/rewrite-clj/issues/168[#168]
 
 === v1.0.699-alpha
 

src/rewrite_clj/custom_zipper/core.cljc

@@ -186,7 +186,7 @@
       zloc)))
 
 (defn-switchable insert-left
-  "Returns zipper with `item` inserted as the left sibling of current node in `zloc`,
+  "Returns zipper with node `item` inserted as the left sibling of current node in `zloc`,
  without moving location."
   [zloc item]
   (let [{:keys [parent position left]} zloc]
@@ -198,7 +198,7 @@
              :position (node/+extent position (node/extent item))))))
 
 (defn-switchable insert-right
-  "Returns zipper with `item` inserted as the right sibling of the current node in `zloc`,
+  "Returns zipper with node `item` inserted as the right sibling of the current node in `zloc`,
   without moving location."
   [zloc item]
   (let [{:keys [parent right]} zloc]
@@ -209,9 +209,9 @@
              :right (cons item right)))))
 
 (defn-switchable replace
-  "Returns zipper with `node` replacing current node in `zloc`, without moving location."
-  [zloc node]
-  (assoc zloc :changed? true :node node))
+  "Returns zipper with node `item` replacing current node in `zloc`, without moving location."
+  [zloc item]
+  (assoc zloc :changed? true :node item))
 
 (defn edit
   "Returns zipper with value of `(apply f current-node args)` replacing current node in `zloc`.
@@ -223,13 +223,13 @@
     (apply clj-zip/edit zloc f args)))
 
 (defn-switchable insert-child
-  "Returns zipper with `item` inserted as the leftmost child of the current node in `zloc`,
+  "Returns zipper with node `item` inserted as the leftmost child of the current node in `zloc`,
   without moving location."
   [zloc item]
   (replace zloc (make-node zloc (node zloc) (cons item (children zloc)))))
 
 (defn-switchable append-child
-  "Returns zipper with `item` inserted as the rightmost child of the current node in `zloc`,
+  "Returns zipper with node `item` inserted as the rightmost child of the current node in `zloc`,
   without moving."
   [zloc item]
   (replace zloc (make-node zloc (node zloc) (concat (children zloc) [item]))))

src/rewrite_clj/zip.cljc

@@ -304,11 +304,11 @@
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.editz
 (defn replace
-  "Return `zloc` with the current node replaced by `value`.
-  If `value` is not already a node, an attempt will be made to coerce it to one.
+  "Return `zloc` with the current node replaced by `item`.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[replace*]] for non-coercing version of replace."
-  [zloc value] (rewrite-clj.zip.editz/replace zloc value))
+  [zloc item] (rewrite-clj.zip.editz/replace zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.editz
 (defn edit
@@ -473,6 +473,8 @@
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.insert
 (defn insert-right
   "Return zipper with `item` inserted to the right of the current node in `zloc`, without moving location.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
+
   Will insert a space if necessary.
 
   Use [[rewrite-clj.zip/insert-right*]] to insert without adding any whitespace."
@@ -482,6 +484,7 @@
 (defn insert-left
   "Return zipper with `item` inserted to the left of the current node in `zloc`, without moving location.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[insert-left*]] to insert without adding any whitespace."
   [zloc item] (rewrite-clj.zip.insert/insert-left zloc item))
@@ -490,6 +493,7 @@
 (defn insert-child
   "Return zipper with `item` inserted as the first child of the current node in `zloc`, without moving location.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[insert-child*]] to insert without adding any whitespace."
   [zloc item] (rewrite-clj.zip.insert/insert-child zloc item))
@@ -498,6 +502,7 @@
 (defn append-child
   "Return zipper with `item` inserted as the last child of the current node in `zloc`, without moving.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[append-child*]] to append without adding any whitespace."
   [zloc item] (rewrite-clj.zip.insert/append-child zloc item))
@@ -922,7 +927,6 @@
   "DEPRECATED: renamed to [[insert-newline-right]]."
   ([zloc n] (rewrite-clj.zip.whitespace/append-newline zloc n))
   ([zloc] (rewrite-clj.zip.whitespace/append-newline zloc)))
-;; TODO: clj-kondo barfs on an empty reader cond
 #?(:clj
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
@@ -1013,14 +1017,24 @@ Returns zipper with location at the leftmost sibling of the current node in `zlo
 NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc] (rewrite-clj.custom-zipper.core/leftmost zloc))
 
+;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
+(defn remove*
+  "Raw version of [[remove]].
+
+Returns zipper with current node in `zloc` removed, with location at node that would have preceded
+  it in a depth-first walk.
+
+NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+  [zloc] (rewrite-clj.custom-zipper.core/remove zloc))
+
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn replace*
   "Raw version of [[replace]].
 
-Returns zipper with `node` replacing current node in `zloc`, without moving location.
+Returns zipper with node `item` replacing current node in `zloc`, without moving location.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
-  [zloc node] (rewrite-clj.custom-zipper.core/replace zloc node))
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
+  [zloc item] (rewrite-clj.custom-zipper.core/replace zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn edit*
@@ -1030,55 +1044,45 @@ Returns zipper with value of `(apply f current-node args)` replacing current nod
 
    The result of `f` should be a rewrite-clj node.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc f & args] (apply rewrite-clj.custom-zipper.core/edit zloc f args))
 
-;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
-(defn remove*
-  "Raw version of [[remove]].
-
-Returns zipper with current node in `zloc` removed, with location at node that would have preceded
-  it in a depth-first walk.
-
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
-  [zloc] (rewrite-clj.custom-zipper.core/remove zloc))
-
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn insert-left*
   "Raw version of [[insert-left]].
 
-Returns zipper with `item` inserted as the left sibling of current node in `zloc`,
+Returns zipper with node `item` inserted as the left sibling of current node in `zloc`,
  without moving location.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc item] (rewrite-clj.custom-zipper.core/insert-left zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn insert-right*
   "Raw version of [[insert-right]].
 
-Returns zipper with `item` inserted as the right sibling of the current node in `zloc`,
+Returns zipper with node `item` inserted as the right sibling of the current node in `zloc`,
   without moving location.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc item] (rewrite-clj.custom-zipper.core/insert-right zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn insert-child*
   "Raw version of [[insert-child]].
 
-Returns zipper with `item` inserted as the leftmost child of the current node in `zloc`,
+Returns zipper with node `item` inserted as the leftmost child of the current node in `zloc`,
   without moving location.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc item] (rewrite-clj.custom-zipper.core/insert-child zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.custom-zipper.core
 (defn append-child*
   "Raw version of [[append-child]].
 
-Returns zipper with `item` inserted as the rightmost child of the current node in `zloc`,
+Returns zipper with node `item` inserted as the rightmost child of the current node in `zloc`,
   without moving.
 
-NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes."
+NOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."
   [zloc item] (rewrite-clj.custom-zipper.core/append-child zloc item))

src/rewrite_clj/zip/edit.clj

@@ -10,11 +10,11 @@
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.editz
 (defn replace
-  "Return `zloc` with the current node replaced by `value`.
-  If `value` is not already a node, an attempt will be made to coerce it to one.
+  "Return `zloc` with the current node replaced by `item`.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[replace*]] for non-coercing version of replace."
-  [zloc value] (rewrite-clj.zip.editz/replace zloc value))
+  [zloc item] (rewrite-clj.zip.editz/replace zloc item))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.editz
 (defn edit

src/rewrite_clj/zip/editz.cljc

@@ -15,12 +15,12 @@
 ;; ## In-Place Modification
 
 (defn replace
-  "Return `zloc` with the current node replaced by `value`.
-  If `value` is not already a node, an attempt will be made to coerce it to one.
+  "Return `zloc` with the current node replaced by `item`.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[replace*]] for non-coercing version of replace."
-  [zloc value]
-  (zraw/replace zloc (node/coerce value)))
+  [zloc item]
+  (zraw/replace zloc (node/coerce item)))
 
 (defn- node-editor
   "Create s-expression from node, apply the function and create

src/rewrite_clj/zip/insert.cljc

@@ -25,6 +25,8 @@
 
 (defn insert-right
   "Return zipper with `item` inserted to the right of the current node in `zloc`, without moving location.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
+
   Will insert a space if necessary.
 
   Use [[rewrite-clj.zip/insert-right*]] to insert without adding any whitespace."
@@ -38,6 +40,7 @@
 (defn insert-left
   "Return zipper with `item` inserted to the left of the current node in `zloc`, without moving location.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[insert-left*]] to insert without adding any whitespace."
   [zloc item]
@@ -50,6 +53,7 @@
 (defn insert-child
   "Return zipper with `item` inserted as the first child of the current node in `zloc`, without moving location.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[insert-child*]] to insert without adding any whitespace."
   [zloc item]
@@ -62,6 +66,7 @@
 (defn append-child
   "Return zipper with `item` inserted as the last child of the current node in `zloc`, without moving.
   Will insert a space if necessary.
+  If `item` is not already a node, an attempt will be made to coerce it to one.
 
   Use [[append-child*]] to append without adding any whitespace."
   [zloc item]

template/rewrite_clj/zip.cljc

@@ -247,7 +247,6 @@
             ^{:deprecated "0.5.0"} prepend-newline
             ^{:deprecated "0.5.0"} append-newline]]}}
 
-;; TODO: clj-kondo barfs on an empty reader cond
 #?(:clj
    #_{:import-vars/import
       {:from [[rewrite-clj.zip.base
@@ -260,7 +259,13 @@
             right left up down
             next prev
             rightmost leftmost
-            replace edit remove
+            remove]]}}
+
+#_{:import-vars/import
+   {:opts {:sym-to-pattern "@@orig-name@@*"
+           :doc-to-pattern "Raw version of [[@@orig-name@@]].\n\n@@orig-doc@@\n\nNOTE: This function does no coercion, does not skip, nor provide any special handling for whitespace/comment nodes."}
+    :from [[rewrite-clj.custom-zipper.core
+            replace edit
             insert-left insert-right
             insert-child
             append-child]]}}