   (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
+  "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))

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

(defn assoc-effect
  "Returns a new `context` with a new effects map that contains `key`
   mapped to the `value`."
  [context key value]
  (interceptor/assoc-effect context key value))

(defn enqueue
  "Add a collection of `interceptors` to the end of `context's` execution `:queue`.
  Returns the updated `context`.

  In an advanced case, this function could allow an interceptor to add new
  interceptors to the `:queue` of a context."
  [context interceptors]
  (interceptor/enqueue context interceptors))


;; --  logging ----------------------------------------------------------------
;; Internally, re-frame uses the logging functions: warn, log, error, group and groupEnd
;; By default, these functions map directly to the js/console implementations,
;; but you can override with your own fns (set or subset).
;; Example Usage:
;;   (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
(defn set-loggers!
  "Change the set (or a subset) of logging functions used by re-frame.
  `new-loggers` should be a map with the same keys as `loggers` (above)"
  [new-loggers]
  (loggers/set-loggers! new-loggers))

(defn console
  "Logs `args` to the console at `level`. 
   Level can be one of `:log` `:error` `:warn` `:debug` `:group` `:groupEnd`.
   If you are writing an extension to re-frame, like prehaps an effect handler,
   you may want to use re-frame logging so that users can configure logging 
   from a central location.

   usage: (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
  "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


   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. 
  
   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
  "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)))


(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 
