Improve comments on handlers

src/re_frame/handlers.cljs

@@ -29,7 +29,7 @@
 ;; -- The Event Conveyor Belt  --------------------------------------------------------------------
 ;;
 ;; Moves events from "dispatch" to the router loop.
-;; This alows for aysnc handling of events.
+;; Allows for the aysnc handling of events.
 ;;
 (def ^:private event-chan (chan))    ;; TODO: how big should we make the buffer?
 
@@ -37,7 +37,14 @@
 ;; -- lookup and call -----------------------------------------------------------------------------
 
 (defn- handle
-  "Look up the handler for the given event, then call it, passing in 2 parameters."
+  "Given an event vector, look up the right handler, then call it.
+  By default, handlers are not assumed to be pure. They are called with
+  two paramters:
+  - the `app-db` atom and
+  - the event vector
+  The handler is assumed to side-effect on the atom, the return value is ignored.
+   To write handlers that are pure functions, use the \"pure\" middleware at handler
+   registration time."
   [event-v]
   (let [event-id    (first-in-vector event-v)
         handler-fn  (get @id->fn event-id)]
@@ -48,7 +55,7 @@
 
 ;; -- router loop ---------------------------------------------------------------------------------
 ;;
-;; In a loop, read events from the dispatch channel, and route them
+;; In a perpretual loop, read events from the dispatch channel, and route them
 ;; to the right handler.
 ;;
 ;; Because handlers occupy the CPU, before each event is handled, hand
@@ -57,7 +64,7 @@
 ;; In odd cases, we need to pause for an entire annimationFrame, to ensure that
 ;; the DOM is fully flushed, before then calling a handler known to hog the CPU
 ;; for an extended period.  In such a case, the event should be laballed with metadata
-;; Example usage:
+;; Example usage (notice the ":flush-dom" metadata):
 ;;   (dispatch ^:flush-dom  [:event-id other params])
 ;;
 ;; router loop
@@ -79,10 +86,11 @@
   [event-v]
   (if (nil? event-v)
     (warn "re-frame: \"dispatch\" is ignoring a nil event.")     ;; nil would close the channel
-    (put! event-chan event-v)))
+    (put! event-chan event-v))
+  nil)   ;; Ensure nil return. See https://github.com/Day8/re-frame/wiki/Returning-False
 
 
-;; TODO: remove sync handling.  I don't like it, even for testing.
+;; TODO: remove sync handling.  I don't like it much, even for testing.
 (defn dispatch-sync
   "Invoke the event handler sycronously, avoiding the async-inducing use of core.async/chan"
   [event-v]