finished first-round documentation for the core fn feajures

src/fogus/me/trammel/impl.clj

@@ -58,17 +58,53 @@
     (build-constraints-map expectations)
     (list* 'f sig)))
 
-(defn collect-bodies [forms]
+(defn collect-bodies
+  "Where the magic happens.  Takes a list representing the idependent constraints for 
+   an unspecified function of the form:
+
+    ([x] :requires (foo x) :ensures (bar %) 
+     [x y] :requires (baz x) (quux y) :ensures (blip %))
+
+   Taking this form `collect-bodies` then partitions it in such a way as to identify
+   the arity-based canstraints and pass each on to `build-contract` which then 
+   returns the HOF body for each arity.
+  "
+  [forms]
   (for [body (->> (partition-by vector? forms)
                   (partition 2))]
     (build-contract body)))
 
 (defn build-forms-map
+  "Works similarly to the `collect-bodies` function *except* for two differences:
+   1. Recognizes and processes a `:body` element
+   2. Requires that multi-arity functions *must* be enclosed in sublists similar to 
+      Clojure's default `fn` form.
+
+   The reason for the former is that the `:body` element refers to the body of the
+   generated function.  Without arity-sepcific body sublists there would be no way to 
+   determine when a body ends and another arity constraint specification begins.  This
+   should be no problem since Clojurist are already accustomed to the multi-arity `fn` 
+   form.  
+
+   This function expects a list of the form:
+
+    ([x] :requires (foo x) (bar n) :ensures (baz %) :body (println x) (frob x))
+
+   or
+
+    (([x] :requires (foo x) :ensures (baz %) :body (frob x)) 
+     ([x y] :requires (foo x y) :ensures (baz %) :body (frob x y)))
+
+   And will return a map keyed by arity vector of the form:
+
+    {[x] {(:requires) ((foo x)), (:body) ((frob x)), (:ensures) ((baz %))}}
+
+   Which can then be used to build a real function definition by looking up the
+   constraints and body for each arity.
+  "
   [forms]
   (for [[[e] & c] (map #(partition-by keyword? %) 
                        (if (vector? (first forms)) 
                          (list forms) 
                          forms))]
     {e (apply hash-map c)}))
-
-