add doc comments

views.reagent.sente/src/views/reagent/sente/client.cljs

@@ -22,16 +22,27 @@
   (reset! send-buffer []))
 
 (defn on-open!
+  "should be called when a new Sente connection is established. ev is the event
+   map provided by Sente where id = :chsk/state, and :open? = true. make sure
+   to call this function on all connection open events, not just the first one."
   [sente-chsk-map {:keys [event id client-id] :as ev}]
   (flush-send-buffer! sente-chsk-map)
   (client/on-open!))
 
 (defn on-receive!
+  "should be called whenever a new message is received by Sente from the server.
+   ev is the event map provided by Sente where id = :chsk/recv. if this function
+   returns true it means the received message was for views.reagent and your
+   application code does not need to handle the event itself."
   [sente-chsk-map {:keys [event id client-id] :as ev}]
   (let [[event-id event-data] event]
     (client/on-receive! event-data)))
 
-(defn event-msg-handler
+(defn default-event-msg-handler
+  "very basic Sente event handler that can be used with Sente's start-chsk-router!
+   which makes sure on-open! and on-receive! are called when appropriate. if your
+   application does not need to do any custom Sente event handling, then you can
+   opt to use this event handler."
   [sente-chsk-map {:keys [event id client-id] :as ev}]
   (let [[ev-id ev-data] event]
     (cond
@@ -43,7 +54,17 @@
       (on-receive! sente-chsk-map ev))))
 
 (defn init!
+  "performs initial configuration necessary to hook Sente into views.reagent as the
+   client/server messaging backend. should be called once on page-load after the
+   Sente channel socket has been created (via make-channel-socket!).
+
+   extra available options specific to views.reagent/sente:
+
+   :use-default-sente-router?
+   - if set, enables the use of a default Sente event handler (set via Sente's
+     start-chsk-router!). if your application does not need to respond to any
+     Sente events itself, then you may wish to use this option."
   [sente-chsk-map & [options]]
   (reset! client/send-fn #(send-fn sente-chsk-map %))
   (if (:use-default-sente-router? options)
-    (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(event-msg-handler sente-chsk-map %))))
+    (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(default-event-msg-handler sente-chsk-map %))))

views.reagent.sente/src/views/reagent/sente/server.clj

@@ -13,25 +13,53 @@
   ((:send-fn sente-chsk-map) uid [:views/refresh [view-sig view-data]]))
 
 (defn on-close!
+  "should be called when a client's Sente connection is closed. ev is the event
+   map provided by Sente where id = :chsk/uidport-close."
   [^Atom view-system {:keys [event id uid client-id ring-req ?reply-fn] :as ev}]
   (server/on-close! view-system uid ring-req))
 
 (defn on-receive!
+  "should be called whenever a Sente event is raised that is *not* a connection
+   closed event (:chsk/uidport-close). ev is the event map provided by Sente
+   for the event. if this function returns true it means the received message
+   was for views.reagent and your application code does not need to handle the
+   event itself."
   [^Atom view-system {:keys [event id uid client-id ring-req ?reply-fn] :as ev}]
   (server/on-receive! view-system uid event ring-req))
 
-(defn event-msg-handler
+(defn default-event-msg-handler
+  "very basic Sente event handler that can be used with Sente's start-chsk-router!
+   which makes sure on-close! and on-receive! are called when appropriate. if your
+   application does not need to do any custom Sente event handling, then you can
+   opt to use this event handler."
   [^Atom view-system {:keys [event id uid client-id] :as ev}]
   (if (= id :chsk/uidport-close)
     (on-close! view-system ev)
     (on-receive! view-system ev)))
 
 (defn init!
+  "initializes the views system and adds Sente-specific configuration to it to
+   enable the necessary hooks into views.reagent. this function acts as a direct
+   replacement to calling views.core/init!, so are able to initialize both views
+   and views.reagent by calling this function. the arguments and return value are
+   the same as in views.core/init! so see that function for more information.
+
+   extra available options specific to views.reagent/sente:
+
+   :context-fn
+   - a function that accepts an initial context map created by views.reagent and
+     allows your application to add any info necessary to the context map passed
+     to various view system functions (such as auth-fn, namespace-fn, etc).
+
+   :use-default-sente-router?
+   - if set, enables the use of a default Sente event handler (set via Sente's
+     start-chsk-router!). if your application does not need to respond to any
+     Sente events itself, then you may wish to use this option."
   ([^Atom view-system sente-chsk-map options]
    (let [options (-> options
                      (assoc :send-fn #(views-send-fn sente-chsk-map %1 %2)))]
      (if (:use-default-sente-router? options)
-       (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(event-msg-handler view-system %)))
+       (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(default-event-msg-handler view-system %)))
      (views/init! view-system options)
      (server/set-context-fn! view-system (:context-fn options))))
   ([sente-chsk-map options]