 ;; filter buttons at the bottom of the display.
 (reg-event-db      ;; part of the re-frame API
   :set-showing     ;; event-id
-  [check-spec-interceptor]
+
+  ;; only one interceptor
+  [check-spec-interceptor]       ;; after event handler runs, check app-db for correctness. Does it still match Spec?
+
+  ;; handler
   (fn [db [_ new-filter-kw]]     ;; new-filter-kw is one of :all, :active or :done
     (assoc db :showing new-filter-kw)))
 
-;; NOTE: here is a rewrite of the event handler above using `path` and `trim-v`
-;; These interceptors are useful, but they are an advanced topic.
-;; It will be illuminating if you compare this rewrite with the original above.
+;; NOTE: below is a rewrite of the event handler (above) using a `path` Interceptor
+;; You'll find it illuminating to compare this rewrite with the original.
+;;
+;; A `path` interceptor has BOTH a before and after action.
+;; When you create one, you supply "a path" into `app-db`, like:
+;; [:a :b 1]
+;; The job of "before" is to replace the app-db with the value
+;; of `app-db` at the nominated path. And, then, "after" to
+;; take the event handler returned value and place it back into
+;; app-db at the nominated path.  So the event handler works
+;; with a particular, narrower path within app-db, not all of it.
+;;
+;; So, `path` operates a little like `update-in`
+;;
 #_(reg-event-db
   :set-showing
 
-  ;; this chain of 3 interceptors wrap the handler. Note use of `path` and `trim-v`
-  [check-spec-interceptor (path :showing) trim-v]
+  ;; this now a chain of 2 interceptors. Note use of `path`
+  [check-spec-interceptor (path :showing)]
 
   ;; The event handler
   ;; Because of the `path` interceptor above, the 1st parameter to
   ;; the handler below won't be the entire 'db', and instead will
   ;; be the value at the path `[:showing]` within db.
-  ;; Also, the use of the `trim-v` interceptor means we can omit
-  ;; the leading underscore from the 2nd parameter (event vector).
-  (fn [old-keyword [new-filter-kw]]
-    new-filter-kw))                  ;; return new state for the path
+  ;; Equally the value returned will be the new value for that path
+  ;; within app-db.
+  (fn [old-showing-value [_ new-showing-value]]
+    new-showing-value))                  ;; return new state for the path
 
 
 ;; usage:  (dispatch [:add-todo  "a description string"])
 (reg-event-db                     ;; given the text, create a new todo
   :add-todo
 
-  ;; The standard set of interceptors, defined above, which we
+  ;; Use the standard interceptors, defined above, which we
   ;; use for all todos-modifying event handlers. Looks after
   ;; writing todos to LocalStore, etc.
-  ;; NOTE: this chain includes `path` and `trim-v`
   todo-interceptors
 
   ;; The event handler function.
   ;; The "path" interceptor in `todo-interceptors` means 1st parameter is the
   ;; value at `:todos` path within `db`, rather than the full `db`.
   ;; And, further, it means the event handler returns just the value to be
-  ;; put into `:todos` path, and not the entire `db`.
-  ;; So, a path interceptor makes the event handler act more like clojure's `update-in`
-  (fn [todos [text]]   ;; because of trim-v,  the 2nd parameter is NOT [_ text]
+  ;; put into the `[:todos]` path, and not the entire `db`.
+  ;; So, againt, a path interceptor acts like clojure's `update-in`
+  (fn [todos [_ text]]
     (let [id (allocate-next-id todos)]
       (assoc todos id {:id id :title text :done false}))))
 

  :clear-completed
  todo-interceptors
  (fn [todos _]
    (->> (vals todos)                ;; find the ids of all todos where :done is true
         (filter :done)
         (map :id)
         (reduce dissoc todos))))    ;; now delete these ids


(reg-event-db

(ns todomvc.events
  (:require
    [todomvc.db    :refer [default-db todos->local-store]]
    [re-frame.core :refer [reg-event-db reg-event-fx inject-cofx path after]]
    [cljs.spec.alpha :as s]))


;; -- Interceptors --------------------------------------------------------------
;;
;; Interceptors are a more advanced topic. So, we're plunging into the deep
;; end here.
;;
;; There is a tutorial on Interceptors in re-frame's `/docs`, but to get
;; you going fast, here's a very high level description ...
;;
;; Every event handler can be "wrapped" in a chain of interceptors. A
;; "chain of interceptors" is actually just a "vector of interceptors". Each
;; of these interceptors can have a `:before` function and an `:after` function.
;; Each interceptor wraps around the "handler", so that its `:before`
;; is called before the event handler runs, and its `:after` runs after
;; the event handler has run.
;;
;; Interceptors with a `:before` action, can be used to "inject" values
;; into what will become the `coeffects` parameter of an event handler.
;; That's a way of giving an event handler access to certain resources,
;; like values in LocalStore.
;;
;; Interceptors with an `:after` action, can, among other things,
;; process the effects produced by the event handler. One could
;; check if the new value for `app-db` correctly matches a Spec.
;;


;; -- First Interceptor ------------------------------------------------------
;;
;; Event handlers change state, that's their job. But what happens if there's
;; a bug in the event handler and it corrupts application state in some subtle way?
;; Next, we create an interceptor called `check-spec-interceptor`.
