 ;;
 (register
   :dispatch-n
-  (fn [val]
-    (if-not (sequential? val)
-      (console :error "re-frame: ignoring bad :dispatch-n value. Expected a collection, got got: " val))
-    (doseq [event val] (router/dispatch event))))
+  (fn [value]
+    (if-not (sequential? value)
+      (console :error "re-frame: ignoring bad :dispatch-n value. Expected a collection, got got: " value))
+    (doseq [event value] (router/dispatch event))))
 
 
 ;; :deregister-event-handler
 ;;
-;; removes an event handler. Expects either a single id (typically a keyword), or a seq of ids.
+;; removes a previously registered event handler. Expects either a single id (
+;; typically a keyword), or a seq of ids.
 ;;
 ;; usage:
-;;   {:deregister-event-handler: :my-id)}
+;;   {:deregister-event-handler :my-id)}
 ;; or:
-;;   {:deregister-event-handler: [:one-id :another-id]}
+;;   {:deregister-event-handler [:one-id :another-id]}
 ;;
 (register
   :deregister-event-handler
-  (fn [val]
+  (fn [value]
     (let [clear-event (partial clear-handlers events/kind)]
-      (if (sequential? val)
-        (doall (map clear-event val))
-        (clear-event val)))))
+      (if (sequential? value)
+        (doall (map clear-event value))
+        (clear-event value)))))
 
 
+;; :db
+;;
+;; reset! app-db with a new value. Expects a map.
+;;
+;; usage:
+;;   {:db  {:key1 value1 key2 value2}}
+;;
 (register
   :db
-  (fn [val]
-    (reset! app-db val)))
+  (fn [value]
+    (reset! app-db value)))
 


(register
  :dispatch
  (fn [val]
    (if-not (vector? val)
      (console :error "re-frame: ignoring bad :dispatch value. Expected a vector, but got: " val)
      (router/dispatch val))))


;; :dispatch-n

;; -- Interceptor -------------------------------------------------------------

(def do-effects
  "An interceptor which actions a `context's` (side) `:effects`.

  For each key in the `:effects` map, call the `effects handler` previously
  registered using `reg-fx`.

  So, if `:effects` was:
      {:dispatch  [:hello 42]
