Fix documentation for re-frame.core ns

Fixes #456 and #216. Adds codox to generate API documentation.

project.clj

@@ -14,12 +14,15 @@
                  [org.clojure/tools.logging "0.4.1"]]
 
   :plugins      [[day8/lein-git-inject "0.0.11"]
-                 [lein-shadow          "0.1.7"]]
+                 [lein-shadow          "0.1.7"]
+                 [lein-codox           "0.10.7"]]
 
   :middleware   [leiningen.git-inject/middleware]
 
   :git-inject {:version-pattern #"v(\d+\.\d+\.\d+.*)"}
 
+  :codox {:namespaces [re-frame.core]}
+
   :profiles {:debug {:debug true}
              :dev   {:dependencies [[binaryage/devtools "1.0.0"]]
                      :plugins      [[lein-ancient       "0.6.15"]

src/re_frame/cofx.cljc

@@ -12,80 +12,21 @@
 (assert (re-frame.registrar/kinds kind))
 
 (defn reg-cofx
-  "Register the given coeffect `handler` for the given `id`, for later use
-  within `inject-cofx`.
-
-  `id` is keyword, often namespaced.
-  `handler` is a function which takes either one or two arguements, the first of which is
-  always `coeffects` and which returns an updated `coeffects`.
-
-  See the docs for `inject-cofx` for example use."
   [id handler]
   (register-handler kind id handler))
 
 
 ;; -- Interceptor -------------------------------------------------------------
 
 (defn inject-cofx
-  "Given an `id`, and an optional, arbitrary `value`, returns an interceptor
-   whose `:before` adds to the `:coeffects` (map) by calling a pre-registered
-   'coeffect handler' identified by the `id`.
-
-   The previous association of a `coeffect handler` with an `id` will have
-   happened via a call to `re-frame.core/reg-cofx` - generally on program startup.
-
-   Within the created interceptor, this 'looked up' `coeffect handler` will
-   be called (within the `:before`) with two arguments:
-     - the current value of `:coeffects`
-     - optionally, the originally supplied arbitrary `value`
-
-   This `coeffect handler` is expected to modify and return its first, `coeffects` argument.
-
-   Example Of how `inject-cofx` and `reg-cofx` work together
-   ---------------------------------------------------------
-
-   1. Early in app startup, you register a `coeffect handler` for `:datetime`:
-
-      (re-frame.core/reg-cofx
-        :datetime                        ;; usage  (inject-cofx :datetime)
-        (fn coeffect-handler
-          [coeffect]
-          (assoc coeffect :now (js/Date.))))   ;; modify and return first arg
-
-   2. Later, add an interceptor to an -fx event handler, using `inject-cofx`:
-
-      (re-frame.core/reg-event-fx        ;; we are registering an event handler
-         :event-id
-         [ ... (inject-cofx :datetime) ... ]    ;; <-- create an injecting interceptor
-         (fn event-handler
-           [coeffect event]
-           ... in here can access (:now coeffect) to obtain current datetime ... )))
-
-   Background
-   ----------
-
-   `coeffects` are the input resources required by an event handler
-   to perform its job. The two most obvious ones are `db` and `event`.
-   But sometimes an event handler might need other resources.
-
-   Perhaps an event handler needs a random number or a GUID or the current
-   datetime. Perhaps it needs access to a DataScript database connection.
-
-   If an event handler directly accesses these resources, it stops being
-   pure and, consequently, it becomes harder to test, etc. So we don't
-   want that.
-
-   Instead, the interceptor created by this function is a way to 'inject'
-   'necessary resources' into the `:coeffects` (map) subsequently given
-   to the event handler at call time."
   ([id]
-  (->interceptor
-    :id      :coeffects
-    :before  (fn coeffects-before
-               [context]
-               (if-let [handler (get-handler kind id)]
-                 (update context :coeffects handler)
-                 (console :error "No cofx handler registered for" id)))))
+   (->interceptor
+     :id      :coeffects
+     :before  (fn coeffects-before
+                [context]
+                (if-let [handler (get-handler kind id)]
+                  (update context :coeffects handler)
+                  (console :error "No cofx handler registered for" id)))))
   ([id value]
    (->interceptor
      :id     :coeffects