 (defn buffer-matrix
   "For the supplied matrix `mat`, returns a new matrix generated by
   padding the beginning and end of each row and column with the
-  supplied value, repeated `buffer-size` times. For example:
+  supplied value, repeated `buffer-size` times.
 
-  (def test-matrix [[0 1 2]
-                    [3 4 5]])
-
-  (buffer-matrix 2 1 test-matrix)
-  => [[1 1 1 1 1 1 1]
-      [1 1 1 1 1 1 1]
-      [1 1 0 1 2 1 1]
-      [1 1 3 4 5 1 1]
-      [1 1 1 1 1 1 1]
-      [1 1 1 1 1 1 1]]"
+  Example usage:
+    (def test-matrix [[0 1 2]
+                      [3 4 5]])
+    (buffer-matrix 2 1 test-matrix) => [[1 1 1 1 1 1 1]
+                                        [1 1 1 1 1 1 1]
+                                        [1 1 0 1 2 1 1]
+                                        [1 1 3 4 5 1 1]
+                                        [1 1 1 1 1 1 1]
+                                        [1 1 1 1 1 1 1]]"
   [buffer-size val [row :as mat]]
   (let [n (-> buffer-size (* 2) (+ (count row)))
         buf-row (repeat n val)]

  "Iterates across the supplied two dimensional matrix, returning a
  lazy sequence of 2-element vectors of the form `[matrix entry,
  neighbor-seq]`. Neighbors outside the matrix are reported as
  nil. For example:

    (def test-matrix [[:0 :1 :2 :3]
                      [:4 :5 :6 :7]
                      [:8 :9 :a :b]
                      [:c :d :e :f]])

    (first (neighbor-scan 1 test-matrix))
    ;=> [:0 ((nil nil nil) (nil :1) (nil :4 :5))]"

  [num-neighbors mat]
  {:pre [(> (count mat)
            (inc (* 2 num-neighbors)))]}

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