   std-interceptors/after)
 
 (def on-changes
-  "Interceptor factory which acts a bit like `reaction`  (but it flows into
-  `db`, rather than out). It observes N paths within `db` and if any of them
-  test not identical? to their previous value  (as a result of a event handler
-  being run) then it runs `f` to compute a new value, which is then assoc-ed
-  into the given `out-path` within `db`.
-
-  Usage:
-
+  "An interceptor factory, which is to say, a function which will return an interceptor. 
+   
+   The returned interceptor will observe N paths within `db`, and if any of them
+   test not identical? to their previous value  (as a result of a event handler
+   being run), then it runs `f` to compute a new value, which is then assoc-ed
+   into the given `out-path` within `db`.
+
+   Example Usage:
+
+   ```clj
       (defn my-f
         [a-val b-val]
         ... some computation on a and b in here)
 
-      (on-changes my-f [:c]  [:a] [:b])
-
-  Put this Interceptor on the right handlers (ones which might change :a or :b).
-  It will:
+      (reg-event-db 
+        :event-id 
+        [(on-changes my-f [:c]  [:a] [:b]) ... other interceptors]  <-- used here
+        (fn [db v]
+           ...))
+    ```
+   
+    Put this Interceptor on the right handlers (ones which might change :a or :b)
+    and it will: 
+   
      - call `f` each time the value at path [:a] or [:b] changes
      - call `f` with the values extracted from [:a] [:b]
      - assoc the return value from `f` into the path  [:c]


   When you register an event handler you have the option of supplying an
   interceptor chain. Any global interceptors you register are effectively
   prepending to this chain in the order that they are registered."
  [interceptor]
  (settings/reg-global-interceptor interceptor))

(defn clear-global-interceptor ;; think unreg-global-interceptor
  "When called with no args, unregisters all global interceptors. When given
   one arg, assumed to be the `id` of a currently registered global
   interceptor, it unregisters the associated interceptor."
  ([]
   (settings/clear-global-interceptors))
  ([id]
   (settings/clear-global-interceptors id)))

;; Utility functions for creating your own interceptors
;;
;;  (def my-interceptor
;;     (->interceptor                ;; used to create an interceptor
;;       :id     :my-interceptor     ;; an id - decorative only
;;       :before (fn [context]                         ;; you normally want to change :coeffects
;;                  ... use get-coeffect  and assoc-coeffect
;;                       )
;;       :after  (fn [context]                         ;; you normally want to change :effects
;;                 (let [db (get-effect context :db)]  ;; (get-in context [:effects :db])
;;                   (assoc-effect context :http-ajax {...}])))))
;;
(defn ->interceptor
  "A utility function for creating interceptors. 
   
   Accepts three optional, named arguments:
     - `:id` - an id for the interceptor (decorative only)
     - `:before` - the before function 
     - `:after`  - the after function 

  (utils/apply-kw interceptor/->interceptor m))

(defn get-coeffect
  "A utility function, used when writing interceptors, typically within a `:before` function. 
   
   When called with one argument, it returns the `:coeffects` map from with that `context`.
   
   When called with two or three arguments, behaves like `clojure.core/get` and
   returns the value mapped to `key` in the `:coeffects` map within `context`, `not-found` or
   `nil` if `key` is not present."
  ([context]
   (interceptor/get-coeffect context))
