 
 ;; -- dispatch ----------------------------------------------------------------
 (defn dispatch
-  "Queue `event` for processing by the event handling machinery.
+  "Queue `event` for processing by re-frame's event handling machinery.
 
    `event` is a vector and the first element is typically a keyword which
    identifies the kind of event.


  This is the most canonical and instructive of the three variations.

  When a node is created from the template, the `signal-fn` will be called and it
  is expected to return the input signal(s) as either a singleton, if there is only
  one, or a sequence if there are many, or a map with the signals as the values.

  The values from returned nominated signals will be supplied as the 1st argument to
  the `a-computation-fn` when it is called - and subject to what this `signal-fn` returns,
  this value will be either a singleton, sequence or map of them (paralleling
  the structure returned by the `signal-fn`).

  This example `signal-fn` returns a vector of input signals.

      (fn [query-vec dynamic-vec]
         [(subscribe [:a-sub])
          (subscribe [:b-sub])])

  The associated computation function must be written
  to expect a vector of values for its first argument:

      (fn [[a b] query-vec]     ;; 1st argument is a seq of two values
        ....)

 values \"flow into\" the `computation function` gets when it is called.

  `reg-sub` can be called in one of three ways, because there are three ways to define the input signals part.
  But note, the 2nd method, in which a `signals function` is explicitly supplied, is the most canonical and instructive. The other
  two are really just sugary variations.

  First, No input signal fucntion given:

      (reg-sub
        :query-id
        a-computation-fn)   ;; has signature:  (fn [db query-vec]  ... ret-value)

     In the absence of an explicit `signals function`, the node's input signal defaults to `app-db`
     and, as a result, the value within `app-db` (a map) is
     is given as the 1st argument when `a-computation-fn` is called.

