         (if (not (= false (get-in spec [:phrasal] true)))
           (gen spec model (+ 1 depth)))))))
 
-(defn get-bolts-for [model spec depth]
+(defn get-bolts-for
+  "Return every possible bolt for the given model and spec."
+  [model spec depth]
+  ;; Wrapper around (defn lightning-bolts) to provide a way to
+  ;; test indexing and memoization strategies.
   (let [result
         ;; TODO: this is an example of obtaining pre-computed bolts
         ;; from a model given a spec and a depth.

(defn generate
  "Return one expression matching spec _spec_ given the model _model_."
  [spec language-model]
  (log/debug (str "(generate) with model named: " (:name language-model)))
  (first (gen spec language-model 0)))

(defn gen
  "Return a lazy sequence of every possible tree given a specification and a model."
  [spec model depth & [from-bolts]]
  (log/trace (str "gen@" depth "; spec=" (show-spec spec)))
  (when (< depth max-depth)
    (let [bolts (or from-bolts

      true (lightning-bolts model spec 0 depth))))

(defn lightning-bolts
  "Return every possible bolt for the given model and spec. Start at the given depth and
   keep generating until the given max-depth is reached."
  [model spec depth max-depth & [use-candidate-parents]]
  ;; 'lightning bolts' look like:
  ;; 
  ;; 
  ;;   H        H    H
