 
 ;; -- subscriptions -----------------------------------------------------------
 (defn reg-sub
-  "For a given `query-id`, register two functions: a `computation` function and an `input signals` function.
-
-  During program execution, a call to `subscribe`, such as `(subscribe [:sub-id 3 \"blue\"])`,
-  will create a new `:sub-id` node in the Signal Graph. And, at that time, re-frame
-  needs to know how to create the node.   By calling `reg-sub`, you are registering
-  'the template' or 'the mechanism' by which nodes in the Signal Graph can be created.
-
-  Repeating: calling `reg-sub` does not create a node. It only creates the template
-  from which nodes can be created later, when they are bought into existence via use of 
-  `subscribe` in a `View Function`.
-
-  `reg-sub` arguments are:
+  "A call to `reg-sub` associates two functions with a `query-id`. 
+   
+  These two functions combine to provide the 'mechanism' for creating a node 
+  in the Signal Graph, for the specified `query-id`. 
   
-  - a `query-id` (typically a namespaced keyword)
-  - a function which returns the inputs required by this kind of node (which can be supplied in one of three ways)
-  - a function which computes the value of this kind of node
-
-  The `computation function` is always the last argument supplied and it is expected to have the signature:
-    `(input-values, query-vector) -> a-value`
-
-  When `computation function` is called, the `query-vector` argument will be the vector supplied to the
-  the `subscribe` which caused the node to be created. So, if the call was `(subscribe [:sub-id 3 \"blue\"])`,
-  then the `query-vector` supplied to the computaton function will be `[:sub-id 3 \"blue\"]`.
-
-  The arguments supplied between the `query-id` and the `computation-function` can vary in 3 ways,
-  but whatever is there defines the `input signals` part of the template, controlling what input
- 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:
+  The three arguments are: 
+   
+  - `query-id` - typically a namespaced keyword (later used in subscribe)
+  - optionally, an `input signals` function which returns the input data
+    flows required by this kind of node. 
+  - a `computation function` which computes the value of the node (from the input data flows)
+     
+  Later, during app execution, a call to `(subscribe [:sub-id 3 :blue])`,
+  will trigger the need for a new Signal Graph node (for the query `[:sub-id 3 :blue]`).
+  And that means creating a new `:sub-id` node. To do that the two functions 
+  associated with `:sub-id` are looked up and used.
+
+  Just to repeat:  calling `reg-sub` does not immediately create a node. It only registers 
+  'the mechanism' (the two functions) by which nodes can be created later, when a node is 
+  bought into existence by the use of `subscribe` in a `View Function`.
+
+  The `computation function` is expected to take two arguments:
+  
+    - `input-values` - the values which flow into this node
+    - `query-vector` - the vector given to `subscribe`
+  
+  and it returns a computed value (which then becomes the output of the node)
+
+  When `computation function` is called, the 2nd `query-vector` argument will be that 
+  vector supplied to the `subscribe`. So, if the call was `(subscribe [:sub-id 3 :blue])`,
+  then the `query-vector` supplied to the computaton function will be `[:sub-id 3 :blue]`.
+
+  The argument(s) supplied between `query-id` and the `computation-function` 
+  can vary in 3 ways, but whatever is there defines the `input signals` part 
+  of `the mechanism`, specifying what input values \"flow into\" the 
+  `computation function` (as the 1st argument) 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 variation - no input signal function given:
 
       (reg-sub
         :query-id

      (subscribe [:items {:colour \"blue\"  :size :small}])
 
  Note: for any given call to `subscribe` there must have been a previous call
  to `reg-sub`, registering the query handler (function) for the `query-id` given.

  #### Hint



  Second - Later, add an interceptor to an -fx event handler, using `inject-cofx`:

      (re-frame.core/reg-event-fx            ;; when registering an event handler
        :event-id
        [ ... (inject-cofx :datetime) ... ]  ;; <-- create an injecting interceptor
        (fn event-handler
          [coeffect event]
            ;;... in here can access (:now coeffect) to obtain current datetime ... 
          )))

  ##### Background

