more docstrings

1 files changed, 33 insertions, 9 deletions

diff --git a/gtwiwtg.lisp b/gtwiwtg.lisp
index 9c50877..0a8a84b 100644
--- a/gtwiwtg.lisp
+++ b/gtwiwtg.lisp
@@ -407,11 +407,24 @@ THIS FUNCTION MODIFIES AND RETURNS ITS GENERATOR ARGUMENT."
 
 (defun inflate! (fn gen)
   "FN is expected to be a function that accepts elements of GEN and
-returns a new generator.  (INFLATE! FN GEN) returns a generator that is
-equivalent to (FUNCALL #'CONCAT! (MAP! FN GEN))
+returns a new generator.  
 
-That is it generates each element of (FN X) for each X in GEN.
+The generator (INFLATE! FN GEN) generates each element of an
+intermediate generator (FN X) for each X generated by GEN.
 
+Here is an example:
+
+> (let ((keys (seq '(:name :occupation :hobbies)))
+        (vals (seq '(\"buckaroo banzai\" 
+                     \"rocker\" 
+                     (\"neuroscience\" \"particle physics\" \"piloting fighter jets\")))))
+     (collect (inflate! #'seq (zip! keys vals))))
+
+ (:NAME \"buckaroo banzai\" 
+  :OCCUPATION \"rocker\" 
+  :HOBBIES (\"neuroscience\" \"particle physics\" \"piloting fighter jets\"))
+
+Caveat: 
 INFLATE! MODIFIES AND RETURNS ITS GENERATOR ARGUMENT."
   (assert (not (dirty-p gen)))
   (let ((orig-fn (next-fn gen))
@@ -471,6 +484,8 @@ An example:
                   (range :from -10 :to 28 :by 6)))
 
  (-10 -4 0 1 2 2 3 4 6 8 8 14 20 26)
+
+WARNING: IF ANY OF THE GENERATORS COMPARE EQL, AN ERROR WILL BE SIGNALLED.
 "
   (let ((all-gens (list* gen1 gen2 gens)))
 
@@ -542,13 +557,13 @@ iteration.
 
 When iteration has concluded, ACC becomes the value of the FOLD form.
 
-Example:
+Example: standard summing
 
 > (fold (sum 0) (x (times 10)) (+ sum x))
 
 55
 
-Example:
+Example: a usless calculation
 
 > (fold (acc 0)
         ((x y) (zip! (times 10) (range :by -1)))
@@ -556,6 +571,19 @@ Example:
 
 #C(0.4498776 9.987898)
 
+Example: building data 
+
+> (fold (plist nil) 
+        ((key val)
+         (zip! (seq '(:name :occupation :hobbies))
+               (seq '(\"buckaroo banzai\" 
+                      \"rocker\" 
+                      (\"neuroscience\" \"particle physics\" \"piloting fighter jets\")))))
+         (cons key (cons val plist)))
+
+ (:HOBBIES (\"neuroscience\" \"particle physics\" \"piloting fighter jets\")
+  :OCCUPATION \"rocker\" :NAME \"buckaroo banzai\")
+
  "
   `(let ((,acc ,init-val))
      (iter (,var-exp ,gen)
@@ -682,7 +710,3 @@ Not meant for general use. just a utility used by THREAD-THROUGH"
   (filter! #'prime-p (range :from 1)))
 
 
-;; merge-sort
-
-(defun gen-sort (seq)
-  ())