 (ns forma.matrix.walk
+  "Functions that move along a 2D array, collecting features of the
+moving window."
   (:use cascalog.api
         [forma.utils :only (nth-in)]
         [forma.matrix.utils :only (insert-into-val
-                                  insert-at)]))
+                                   insert-at)]))
 
 (defn walk-matrix
-  "Walks along the rows and columns of a matrix at the given window
-  size, returning all (window x window) snapshots."
+  "Returns a sequence of matrices, after walking along the rows and
+  columns of the given matrix a the specified window size and
+  returning all window-by-window snapshots.
+
+  Example usage:
+    (def mat [[0 1 2] [3 4 5]])
+    (walk-matrix mat 2) => [[[0 1]
+                             [3 4]]
+                            [[1 2]
+                             [4 5]]]"
   [m window]
   (mapcat (comp (partial apply map vector)
                 (partial map (partial partition window 1)))

           (apply concat)
           (filter (complement nil?))
           (apply f)))))


               (repeat (* 2 buffer-size) buf-row))))

(defn wipe-out
  "Accepts a nested collection and a sequence of keys, and returns a new
  collection generated by removing the value located at the position
  indicated by the supplied key sequence.

  Example usage:
    (def test-matrix [[0 1 2] [3 4 5]])
    (wipe-out test-matrix [1 2]) => [[0 1 2] [3 4]]"
  [coll [k & ks]]
  {:pre [(or (nil? k) (coll? coll))]}
  (if-not k
