better documentation

README.mediawiki

@@ -23,8 +23,20 @@ passed to it in the order in which they were passed. If the
 callector function is called without arguments it returns the
 current list of values. 
 
+   (with-collector (col)
+       (col 1)
+       (col 2)
+       (col 3)
+       (col)) => (1 2 3)
+
 Mapping collectors mutate the collected value while collecting it.
 
+   (with-mapping-collector (col (x) (* 2 x))
+       (col 1)
+       (col 2)
+       (col 3)
+       (col)) => (2 4 6)
+
 
 === make-reducer / with-reducer ===
 
@@ -58,8 +70,20 @@ passed to it in the order in which they were passed. If the
 appender function is called without arguments it returns the
 current list of values.
 
+    (with-appender (app)
+       (app '(1 2))
+       (app '(2 3))
+       (app '(3 4))
+       (app)) => (1 2 2 3 3 4)
+
 Mapping appenders mutate the collected values while collecting them.
 
+   (with-mapping-appender (app (l) (mapcar #'(lambda (x) (* 2 x)) l))
+       (app '(1 2))
+       (app '(2 3))
+       (app '(3 4))
+       (app)) => (2 4 4 6 6 8)
+
 
 === make-string-builder / with-string-builder / with-string-builder-output ===
 

collectors.lisp

@@ -186,7 +186,15 @@ current list of values."
   "Bind NAME to a collector function and execute BODY. If
   FROM-END is true the collector will actually be a pusher, (see
   MAKE-PUSHER), otherwise NAME will be bound to a collector,
-  (see MAKE-COLLECTOR)."
+  (see MAKE-COLLECTOR).
+
+    (with-appender (app)
+       (app '(1 2))
+       (app '(2 3))
+       (app '(3 4))
+       (app)) => (1 2 2 3 3 4)
+
+  "
   (alexandria:with-unique-names (appender)
     `(let ((,appender (make-appender ,initial-value)))
        (flet ((,name (&rest items)
@@ -199,7 +207,13 @@ current list of values."
   "Bind NAME to a collector function and execute BODY. If
   FROM-END is true the collector will actually be a pusher, (see
   MAKE-PUSHER), otherwise NAME will be bound to a collector,
-  (see MAKE-COLLECTOR)."
+  (see MAKE-COLLECTOR).
+    (with-collector (col)
+       (col 1)
+       (col 2)
+       (col 3)
+       (col)) => (1 2 3)
+  "
   (alexandria:with-unique-names (collector)
     `(let ((,collector ,(if from-end
                             `(make-pusher ,initial-value ,collect-nil)