Documentation for EventEmitter

src/moira/log/event_emitter.cljs

@@ -1,14 +1,41 @@
 (ns moira.log.event-emitter
+  "Create the Application Log, a central hub for propagating Application
+  Events."
+
   (:require [moira.event :as event]))
 
 (defprotocol Listenable
-  (emit [this e])
-  (listen [this f] [this k f])
-  (unlisten [this] [this f] [this k f]))
+  "Provide means to subscribe to or unsubscribe from events of a specific
+  type."
+
+  (emit [this e]
+    "Dispatch event `e` to all listeners.
+
+    `:type` should be defined as keyword.")
+
+  (listen [this f] [this k f]
+    "Register `f` to be notified about events of type `k`.
+
+    If `k` is not given trigger `f` on all events.")
+
+  (unlisten [this] [this f] [this k f]
+    "Unregister `f` to no longer be triggered on events of type `k`.
+
+    If `k` is not given unregister `f` from all events. If both `k` and `f` are
+    not specified unregister all handlers from all events."))
 
 (defprotocol Resumable
-  (pause [this])
-  (resume [this]))
+  "Pause dispatching events and buffer events to notify handlers on resume."
+
+  (pause [this]
+    "Pause dispatching of Application Events.
+
+    Buffer events for later dispatch.")
+
+  (resume [this]
+    "Resume dispatching of Application Events.
+
+    All buffered events are triggered first and in order."))
 
 (def ^:private empty-registry {::any []})
 
@@ -27,7 +54,16 @@
     (fire event registry)
     (finally (resume this))))
 
-(deftype EventEmitter [factory !registry !buffer !paused?]
+(deftype
+ ^{:doc
+   "Produce Application Events and propagate them to registered listeners.
+
+   Dispatching of events can be paused and resumed."}
+
+ EventEmitter
+
+ [factory !registry !buffer !paused?]
+
   Listenable
   (emit [this e]
     (let [e* (event/->event factory e)]
@@ -55,7 +91,11 @@
       (vswap! !buffer pop))
     (vreset! !paused? false)))
 
-(defn create []
+(defn create
+  "Create [[EventEmitter]] instance to serve as Application Log."
+
+  []
+
   (->EventEmitter (event/factory)
                   (volatile! empty-registry)
                   (volatile! #queue [])