 
    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."
+   prepending to this chain. 
+  
+   Global interceptors are run 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
+  "Unregisters (removes) global interceptors. 
+   
+   When called with no arguments, it unregisters all global interceptors. When given
+   one argument, 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
  "When called with one arg, returns the coeffects map from the `context`.
   When called with two or three args, behaves like `clojure.core/get`, 
   returns the value mapped to `key` in the coeffects map, `not-found` or
   `nil` if `key` is not present."
  ([context]
   (interceptor/get-coeffect context))

   (interceptor/get-effect context key not-found)))

(defn assoc-effect
   "A utility function, used when writing interceptors, typically within an `:after` function. 
   
   Adds or updates a key/value pair in the `:effects` map within `context`. "
  [context key value]
  (interceptor/assoc-effect context key value))

(defn enqueue
  "An advanced utility function, used when writing interceptors, typically within a `:before` function. 
  
  Adds a collection of `interceptors` to the end of `context's` execution `:queue`, and then
  returns the updated `context`."
  [context interceptors]
  (interceptor/enqueue context interceptors))


;; --  logging ----------------------------------------------------------------

(defn set-loggers!
  "Internally, re-frame uses the logging functions: `warn`, `log`, `error`, `group` and `groupEnd`

   By default, these functions map directly to the default `js/console` implementations,
   but you can override with your own fns (set or subset).
   
   `new-loggers` should be a map with the same keys as `loggers` 

   Example Usage:
   ```clj
     (defn my-fn [& args]  (post-it-somewhere (apply str args)))  ;; here is my alternative
     (re-frame.core/set-loggers!  {:warn my-fn :log my-fn})       ;; override the defaults with mine
   ```   
   "
  [new-loggers]
  (loggers/set-loggers! new-loggers))


(defn console
  "A utility function designed to be used by libraries which are extending re-frame, like 
   perhaps an effect handler, which want to produce output via re-frame's loggers. 
   
   It will write `args` to the js/console at `level`.
   
   `level` can be one of `:log` `:error` `:warn` `:debug` `:group` `:groupEnd`.
   
   Example usage: 
   
   ```clj 
     (console :error \"Oh, dear God, it happened:\" a-var \"and\" another)
     (console :warn \"Possible breach of containment wall at:\" dt)
   ```
   "
  [level & args]
  (apply loggers/console (into [level] args)))

;; -- unit testing ------------------------------------------------------------

(defn make-restore-fn
  "A utility function, typically used in testing. 
   
   Checkpoints the state of re-frame and returns a function which, when
   later called, will restore re-frame to that checkpointed state.

   Checkpoint includes app-db, all registered handlers and all subscriptions.
  "
  []
  (let [handlers @registrar/kind->id->handler
