 ;; ---------------------------------------------------------------------------
 
 (defn vector
+  "Create a generator whose elements are chosen from `gen`. The count of the
+  vector will be bounded by the `size` generator parameter."
   [gen]
   [:gen (fn [rand-seed size]
     (let [num-elements (Math/abs (call-gen int rand-seed size))]

;; ---------------------------------------------------------------------------

(defn pair
  [a b]
  [:gen (fn [rand-seed size]
    [(call-gen a rand-seed size)

     (clojure.core/map (partial call-gen generator r) size-seq))))

(defn sample
  "Return a sequence of `num-samples` (default 10)
  realized values from `generator`."
  ([generator]
   (sample generator 10))
  ([generator num-samples]
