     [clojure.set               :as set]))
 
 
-;; XXX move API functions up to this core level - to enable code completion and auto-generated docs
+;; This namespace defines the re-frame API
+
+;; When originally writing this re-frame API namespace, we used
+;; this technique:
+;;    (def api-name (deeper.namespace/where-the-defn-is))
+;;
+;; Turns out this technique makes it hard:
+;;   - to auto-generate API docs
+;;   - for IDEs to provide code completion on functions in the API.
+;;
+;; Which is annoying. But there are pros and cons and we haven't yet
+;; revisited the decision. So, sorry, in advance. To compensate we've
+;; added more nudity to the official docs.
 
 
 ;; --  dispatch ---------------------------------------------------------------
-(def dispatch         router/dispatch)
-(def dispatch-sync    router/dispatch-sync)
+(def dispatch       router/dispatch)
+(def dispatch-sync  router/dispatch-sync)
 
 
 ;; --  subscriptions ----------------------------------------------------------
-(def reg-sub             subs/reg-sub)
-(def subscribe           subs/subscribe)
-
-(def clear-sub    (partial registrar/clear-handlers subs/kind))
+(def reg-sub        subs/reg-sub)
+(def subscribe      subs/subscribe)
+
+(def clear-sub (partial registrar/clear-handlers subs/kind))  ;; think unreg-sub
 (def clear-subscription-cache! subs/clear-subscription-cache!)
 
 (defn reg-sub-raw

;; If you are writing an extension to re-frame, like perhaps
;; an effects handler, you may want to use re-frame logging.
;;
;; usage:  (console :error "this is bad: " a-variable " and " anotherv)
;;         (console :warn "possible breach of containment wall at: " dt)
(def console loggers/console)



(def on-changes  std-interceptors/on-changes)


;; 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
