 (ns life.matrix
+  "Implements functionality to duplicate APL operations used in Life"
   (:use [clojure.core.matrix]))
 
-(defn nbool [f] (fn [v] (if (f v) 1 0)))
+(defn nbool
+  "Create a function from a boolean function, mapping a truthy value to 1 or 0.
+   e.g. ((nbool not) false) => 1
+        ((nbool not) true) => 0"
+  [f] (fn [v] (if (f v) 1 0)))
 
 (defn takeof
+  "Creates a matrix of a given shape that contains a given matrix 'a'.
+   If the new matrix is smaller than the source matrix, then the source
+   matrix is truncated.
+   If the new matrix is larger than the source matrix in any dimension,
+   then it is padded out using the 'default' value, or 0 if not provided."
   ([sh a] (takeof sh a 0))
   ([sh a default]
    (let [src-shape (shape a)]

                         (apply mget a idx)
                         default))))))

(defn and* [a b] (emap (nbool #(= 2 %)) (add a b)))

(defn or* [a b] (emap (nbool #(not (zero? %))) (add a b)))

(defn outer [a b]
  (array
    (for [x a]
      (for [y b]
        {:a x :b y}))))

(defn outer-fn [f x y]
  (fn [m]
    (emap (fn [{:keys [a b]}] (f (f m 0 a) 1 b))
          (outer x y))))

(defn =x [a]
  (fn [x] (emap (nbool #(= x %)) a)))

(defn power [f n]
  (case n
    0 identity
    1 f

          r
          (recur (f r) (dec i)))))))

(defn power-limit
  "Finds the fixpoint of a function starting at a given argument.
   The function is repeatedly applied to the result of the previous application
   until the result from the function is the same as the argument that led to it.
   e.g. (power-limit #(min (inc %) 10) 1) => 10"
  [f a]
  (loop [a a]
    (let [r (f a)]
      (if (= r a)
