more docstring edits

1 files changed, 36 insertions, 36 deletions

diff --git a/gtwiwtg.lisp b/gtwiwtg.lisp
index bb377e1..d94b7fd 100644
--- a/gtwiwtg.lisp
+++ b/gtwiwtg.lisp
@@ -6,15 +6,15 @@
 ;; None of the following are meant to be called directly by users of the library.
 
 (defgeneric next (gen)
-  (:documentation "Returns the next value of this generator, if
-  available. Unspecified behavior if the generator has been exhausted."))
+  (:documentation "Returns the next value of the generator GEN, if
+  available. Unspecified behavior if the GEN has been exhausted."))
 
 (defgeneric has-next-p (gen)
-  (:documentation "Returns true if next can be called on the generator"))
+  (:documentation "Returns true if next can be called on the generator GEN."))
 
 (defgeneric stop (gen)
   (:documentation "Explicitly stops the generator. Specialize :after
-  methods to implement any clean-up that needs to be done when the
+  methods to implement any clean up that needs to be done when the
   generator has been consumed."))
 
 ;;; Base Generator Class ;;; 
@@ -30,7 +30,7 @@
     :initform nil
     :documentation "Indicates whether or not this generator has been
     explicitly stopped. All consumers explicitly stop the generators
-    the consume.")))
+    they consume.")))
 
 (defmethod stop ((g generator!))
   (setf (stopped-p g) t))
@@ -131,7 +131,7 @@
 
 (defun range (&key (from 0) to (by 1) inclusive)
   "Create a generator that produces a series of numbers between FROM
-and TO with step size of BY.
+and TO with a step size of BY.
 
 When INCLUSIVE is non NIL, then TO will be produced by the generator
 if it would be the last member of generate series.  
@@ -154,8 +154,8 @@ E.g.
 
  (0 3 6 9)
 
-If TO is NIL, then the generator produces an infinite sequence.
-
+If TO is NIL, then the generator produces an infinite series of
+values.
 "
   (let ((comparator (if (plusp by)
                         (if inclusive #'<= #'<)
@@ -172,7 +172,7 @@ If TO is NIL, then the generator produces an infinite sequence.
 
 (defun seq (sequence &key (start 0))
   "Turns a sequecne (a list, vector, string, etc) into a
-generator. The resulting generator will generate exactly the memebers
+generator. The resulting generator will generate exactly the members
 of the sequence."
   (assert (typep sequence 'sequence))
   (if (consp sequence)
@@ -183,13 +183,13 @@ of the sequence."
                      :index (1- start))))
 
 (defun from-thunk-until (thunk &key (until (constantly nil)) clean-up)
-  "Creates a generator that produces a series of value by successively
+  "Creates a generator that produces a series of values by successively
 calling (FUNCALL THUNK).  The iterator stops whenever (FUNCALL UNTIL)
 is non null.
 
-If a CLEAN-UP thunk is supplied, it will be run after consumption of
-the new generator has finished. I.e. when passing this form to a
-consumer such as FOR, FOLD, COLLECT, etc.
+If a CLEAN-UP thunk is supplied, it will be run after the consumption
+of the new generator has finished. (Consumers are forms like FOR,
+COLLECT, FOLD, and so on.)
 
 By default, UNTIL is the function (CONSTANTLY NIL). I.e. it will
 generate forever."
@@ -219,13 +219,13 @@ generator, see FROM-THUNK-UNTIL."
 (defun from-recurrence (rec n-1 &rest n-m)
   "Creates a generator from a recurrence relation.
 
-REC is a function of K arguments.
+REC is a function of M arguments.
 
 The Nth value of the series generated by the new generator is the result of
-calling REC on the previoius K results.
+calling REC on the previoius M results.
 
 N-1 and N-M are used to initialize the recurrence. (1+ (LENGTH N-M))
-should be K, the number of arguments acepted by REC.
+should be M, the number of arguments acepted by REC.
 
 Example
 
@@ -244,8 +244,8 @@ Example
 
 
 (defun repeater (&rest args)
-  "Produces a generator that produces an infinite series consisting in
-the values passed as ARGS looped forever."
+  "Creates a generator that produces an infinite series consisting in
+the the values of ARGS looped forever."
   (let ((state (copy-list args)))
     (from-thunk
      (lambda ()
@@ -264,13 +264,16 @@ the values passed as ARGS looped forever."
   "Create a generator from a STREAM.
 
 You must supply as STREAM-READER function that accepts the stream as
-its only argument and returns NIL if the stream has run out of input,
+its only argument and returns NIL when the stream has run out of data,
 Non-NIL otherwise.
 
-A quirk is that the last value returned from this generator is NIL.
+The new generator will return NIL as its final generated value..
 
-Consumers of the new generator will ensure that the stream is properly
-closed..
+Consumers of the new generator (forms like FOR, FOLD, COLLECT, and so
+on) will ensure that the stream is properly closed - you don't need to
+worry.  If, however, you create a stream-backed-generator but do not
+actually consume it, then the stream will not be properly closed.
+Always consume your generators by passing them to a consumer!
 
 Here is an example:
 
@@ -287,13 +290,12 @@ Here is an example:
 
 
 (defun file-lines (file)
-  "Creates a generator that produces the lines of a file.  The stream
-to the file is closed when the generator finishes.
-
-FILE is either a path to a file.
+  "Creates a generator that produces the lines of a file. See
+  FROM-INPUT-STREAM for more details about stream-backed-generators.
 
-Returns NIL on the last iteration.
+FILE is  a path to a file.
 
+The last generated value of the returned generator will be NIL.
 "
   (from-input-stream (open file)
                      (lambda (stream) (read-line stream nil nil))))
@@ -302,9 +304,9 @@ Returns NIL on the last iteration.
   "Creates a generator that produces the characters of a file. The
 stream to the file is closed when the generator finishes.
 
-FILE is either a path to a file.
+FILE is  a path to a file.
 
-Returns NIL on the last iteration.
+The last generated value of the returned generator will be NIL.
 "
   (from-input-stream (open file)
                      (lambda (stream) (read-char stream nil nil))))
@@ -313,9 +315,9 @@ Returns NIL on the last iteration.
   "Creates a generator that produces the bytes of a file. The
 stream to the file is closed when the generator finishes.
 
-FILE is either a path to a file.
+FILE is  a path to a file.
 
-Returns NIL on the last iteration.
+The last generated value of the returned generator will be NIL.
 "
   (from-input-stream (open file :element-type '(unsigned-byte 8))
                      (lambda (stream) (read-byte stream nil nil))))
@@ -358,12 +360,11 @@ Returns NIL on the last iteration.
 (defun map! (map-fn gen &rest gens)
   "Maps a function over a number of generators, returning a generator
 that produces values that result from calling MAP-FN on those
-generators' elements, in sequence.
+generators' values, in sequence.
 
 The resulting generator will stop producing values as soon as any one
 of the source generators runs out of arguments to pass to
-MAP-FN. I.e. The mapped generator is as long as the shortest argument
-generators.
+MAP-FN. I.e. The new generator is as long as the shortest argument.
 
 Error Conditions:
  - If any of the generators compare EQL an error will be signalled
@@ -382,8 +383,7 @@ Error Conditions:
        (dolist (g all-gens) (stop g))))))
 
 (defun filter! (pred gen)
-  "Produces a generator that filters out members of GEN that are NIL
-when applied to PRED.
+  "Creats a generator that generates the values of GEN for which PRED is non null.
 
 Error Condition:
  - If GEN has been used elsewhere, an error will be signalled.