    (registrar/clear-handlers subs/kind query-id)))
 
 (defn clear-subscription-cache!
-  "Causes all subscriptions to be removed from the cache.
-  Does this by:
-     1. running `on-dispose` on all cached subscriptions
-     2. Each `on-dispose` will perform the removal of themselves.
-
-  This is for development time use. Useful when reloading Figwheel code
-  after a React exception, because React components won't have been
+  "Removes all subscriptions from the cache.
+
+  This is for development time use. Useful when hot realoding reloading 
+  to subscription code or after a React/render exception, because React components won't have been
   cleaned up properly. And this, in turn, means the subscriptions within those
-  components won't have been cleaned up correctly. So this forces the issue."
+  components won't have been cleaned up correctly. So this forces the issue.
+     
+   Implementation note: it calls `on-dispose` for each cached item, 
+   and it is that fucntion which actually performs the cache removal.
+   "
   []
   (subs/clear-subscription-cache!))
 
 (defn reg-sub-raw
   "This is a low level, advanced function.  You should probably be
-  using reg-sub instead.
-  Docs in
+  using `reg-sub` instead.
+   
+  Some docs are available in
   <a href=\"http://day8.github.io/re-frame/flow-mechanics/\" target=\"_blank\">http://day8.github.io/re-frame/flow-mechanics/</a>"
   [query-id handler-fn]
   (registrar/register-handler subs/kind query-id handler-fn))

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

(defn assoc-effect
   "A utility function, typically used when writing an interceptor's `: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, typically used when writing an interceptor's `:before `function. 
  
  Adds a collection of `interceptors` to the end of `context's` execution `:queue`, and then
  returns the updated `context`."

      nil)))

(defn purge-event-queue
  "Removes all events currently queued for processing"
  []
  (router/purge re-frame.router/event-queue))


;; -- Event Processing Callbacks  ---------------------------------------------

