Improve comments in todomvc example

examples/todomvc/src/todomvc/db.cljs

@@ -15,23 +15,27 @@
 ;; How is this done? Look in handlers.cljs and you'll notice that all handers
 ;; have an "after" middleware which does the schema re-check.
 ;;
-;; None of this is strictly necessary. It could  be omitted. But we find it
+;; None of this is strictly necessary. It could be omitted. But we find it
 ;; good practice.
 
-(def schema {;; a sorted-map is used to hold the todos.
-             :todos    (s/both PersistentTreeMap        ;; ensure sorted-map, not just map
-                               
-                               ;; each todo is keyed by its integer :id value
-                               {s/Int {:id s/Int :title s/Str :done s/Bool}})
+(def TODO-ID s/Int)
+(def TODO    {:id TODO-ID :title s/Str :done s/Bool})
+(def schema  {:todos (s/both
+                       PersistentTreeMap   ;; it is a sorted-map (not just a map)
+                       {TODO-ID TODO})     ;; in this map, each todo is keyed by its :id
 
-             ;; controls what todos are shown/visible to the user
-             :showing  (s/enum :active :done :all)})
+              :showing  (s/enum            ;; what todos are shown to the user?
+                          :all             ;; all todos are shown
+                          :active          ;; only todos whose :done is false
+                          :done            ;; only todos whose :done is true
+                          )})
 
 
 
 ;; -- Default app-db Value  ---------------------------------------------------
 ;;
 ;; When the application first starts, this will be the value put in app-db
+;; Unless, or course, there are todos in the LocalStore (see further below)
 ;; Look in core.cljs for  "(dispatch-sync [:initialise-db])"
 ;;
 
@@ -43,9 +47,9 @@
 
 ;; -- Local Storage  ----------------------------------------------------------
 ;;
-;; Part of the todomvc challenge is to store the todos in LocalStorage, and
+;; Part of the todomvc challenge is to store todos in LocalStorage, and
 ;; on app startup, reload the todos from when the program was last run.
-;; But not the setting for "showing" filter. Just the todos.
+;; But we are not to load the setting for the "showing" filter. Just the todos.
 ;;
 
 (def lsk "todos-reframe")     ;; localstore key

examples/todomvc/src/todomvc/handlers.cljs

@@ -7,12 +7,14 @@
 
 ;; -- Middleware --------------------------------------------------------------
 ;;
+;; See https://github.com/Day8/re-frame/wiki/Using-Handler-Middleware
+;;
 
 (defn check-and-throw
-      "throw an exception if db doesn't match the schema."
-      [a-schema db]
-      (if-let [problems  (s/check a-schema db)]
-         (throw (js/Error. (str "schema check failed: " problems)))))
+  "throw an exception if db doesn't match the schema."
+  [a-schema db]
+  (if-let [problems  (s/check a-schema db)]
+    (throw (js/Error. (str "schema check failed: " problems)))))
 
 ;; after an event handler has run, this middleware can check that
 ;; it the value in app-db still correctly matches the schema.
@@ -22,7 +24,7 @@
 (def ->ls (after todos->ls!))    ;; middleware to store todos into local storage
 
 ;; middleware for any handler that manipulates todos
-(def todo-middleware [check-schema-mw ;; after ever event handler make sure the schema is still valid
+(def todo-middleware [check-schema-mw ;; ensure the schema is still valid
                       (path :todos)   ;; 1st param to handler will be value from this path
                       ->ls            ;; write to localstore each time
                       trim-v])        ;; remove event id from event vec
@@ -31,24 +33,25 @@
 ;; -- Helpers -----------------------------------------------------------------
 
 (defn allocate-next-id
-  "Returns the next daypart id.
-  Assumes dayaprts are sorted.
+  "Returns the next todo id.
+  Assumes todos are sorted.
   Returns one more than the current largest id."
   [todos]
   ((fnil inc 0) (last (keys todos))))
 
 
-;; -- Handlers ----------------------------------------------------------------
+;; -- Event Handlers ----------------------------------------------------------
 
                                   ;; usage:  (dispatch [:initialise-db])
 (register-handler                 ;; On app startup, ceate initial state
   :initialise-db                  ;; event id being handled
-  check-schema-mw
+  check-schema-mw                 ;; afterwards: check that app-db matches the schema
   (fn [_ _]                       ;; the handler being registered
     (merge default-value (ls->todos))))  ;; all hail the new state
 
 
-(register-handler                 ;; this handler changes the footer filter
+                                  ;; usage:  (dispatch [:set-showing  :active])
+(register-handler                 ;; this handler changes the todo filter
   :set-showing                    ;; event-id
   [check-schema-mw (path :showing) trim-v]  ;; middleware  (wraps the handler)
 
@@ -61,6 +64,7 @@
     new-filter-kw))               ;; return new state for the path
 
 
+                                   ;; usage:  (dispatch [:add-todo  "Finsih comments"])
 (register-handler                  ;; given the text, create a new todo
   :add-todo
   todo-middleware