         (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.

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

(defn lightning-bolts
  [model spec depth max-depth & [use-candidate-parents]]
  ;; Generate 'lightning bolts':
  ;; 
  ;; 
  ;;   H        H    H

(defn generate
  "Return one expression matching spec _spec_ given the model _model_."
  [spec language-model]
  ;; 
  ;; Return the tree of an expression, generated by the given model,
  ;; that satisfies given spec:
  ;;
  ;; The tree will look like:
  ;; 
  ;; Where H is the head of a certain node in the tree, and C
  ;; is the complement. Terminal nodes are lexemes given by the model.
  ;;
  ;;       H   
  ;;      / \  
  ;;     H   C 
  ;;        / \  
  ;;       H   C 
  ;; 
  ;; A convenient wrapper around (defn gen) (below).

  (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 expression given the spec and model,
  each of whose depth is no greater than the given depth. Trees are returned in 
  ascending depth."
  [spec model depth & [from-bolts]]
  ;; 
  ;; Given a spec and a model, return the (potentially infinite) set
  ;; of all trees, in ascending depth, that satisfy the given spec.
  ;;
  ;;
  ;; These trees look like:
  ;;
  ;;  First all the depth=0 trees (simply lexemes) that satisfy the spec:
  ;; 
  ;;         H .. H ..

  ;;   Then we have the trees of depth=1 that satisfy the spec:
  ;; 
  ;;       H         H
  ;;  ..  / \  ..   / \ ..
  ;;     H   C     C   H
  ;;
  ;;   And then all trees of depth=2 that satisfy the spec:
  ;;
  ;; 
  ;;       H            H
  ;;      / \          / \
  ;;  .. H   C  ..    C   H .. 
  ;;    /            / \
  ;;   H            C   H
  ;;
  ;; And so on.
  ;;
  ;;
  (log/trace (str "gen@" depth "; spec=" (show-spec spec)))
  (when (< depth max-depth)
    (let [bolts (or from-bolts
