Further API doc refinements

docs/API.md

@@ -1,11 +1,19 @@
 ## The re-frame API
 
 Orientation:
-  1. The API is provided by [re-frame.core](/src/re_frame/core.cljc) which means:
-     - it will be worth your while to browse this namespace sometime
-     - to use re-frame, you'll need to `require` it
+  1. The API is provided by [re-frame.core](/src/re_frame/core.cljc):
+     - at some point, it will be worth your time to browse it
+     - to use re-frame, you'll need to `require` it, perhaps this way ...
+     ```
+     (ns  my.namespace
+       (:require [re-frame.core :as rf]))
+                 
+     ... now use rf/reg-event-fx  or rf/subscribe
+     ```
+          
   2. The API is small. Writing an app, you'll be using less than 10 API functions. Maybe just 5.
-  3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36) but 
+  3. There's no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36) 
+     but, as a substitute, 
      the links below take you to the doc strings of often-used API functions. 
 
 ## Doc Strings For API Functions 
@@ -17,8 +25,8 @@ The core API consists of:
   - [subscribe](/src/re_frame/subs.cljc#L67-L83)
 
 Occasionally, you'll need to use:  
-  - [reg-fx](/src/re_frame/fx.cljc#L17-L39)
-  - [reg-cofx](/src/re_frame/cofx.cljc#L14-L21) and [inject-cofx](/src/re_frame/cofx.cljc#L28-L79)
+  - [reg-fx](/src/re_frame/fx.cljc#L17-L40)
+  - [reg-cofx](/src/re_frame/cofx.cljc#L14-L22) and [inject-cofx](/src/re_frame/cofx.cljc#L29-L80)
      
 And, finally, there are builtin Interceptors which are useful:
   - [path](/src/re_frame/std_interceptors.cljc#L149-L173)

src/re_frame/cofx.cljc

@@ -12,13 +12,14 @@
 (assert (re-frame.registrar/kinds kind))
 
 (defn reg-cofx
-  "Register the given coeffect `handler` for the given coeffect `id`.
+  "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 values, the first of which is
-  always `context` and which returns an updated `context`.
+  `handler` is a function which takes either one or two arguements, the first of which is
+  always `coeffects` and which returns an updated `coeffects`.
 
-  Please see the docs for `inject-cofx` for example use."
+  See the docs for `inject-cofx` for example use."
   [id handler]
   (register-handler kind id handler))
 
@@ -30,18 +31,18 @@
    whose `:before` adds to the `:coeffects` (map) by calling a pre-registered
    'coeffect handler' identified by the `id`.
 
-   It is expected that a `coeffect handler` will previously have been registered
-   for the given `id`, via a call to `re-frame.core/reg-cofx`.
+   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.
 
-   The `coeffect handler` (identified by `id`) will be called (at `:before` time)
-   with two arguments:
+   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 argument.
+   This `coeffect handler` is expected to modify and return its first, `coeffects` argument.
 
-   Example Use
-   -----------
+   Example Of how `inject-cofx` and `reg-cofx` work together
+   ---------------------------------------------------------
 
    1. Early in app startup, you register a `coeffect handler` for `:datetime`:
 
@@ -53,12 +54,12 @@
 
    2. Later, add an interceptor to an -fx event handler, using `inject-cofx`:
 
-      (re-frame.reg-event-fx
+      (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]
-           ... can access (:now coeffect) to obtain current datetime ... )))
+           ... in here can access (:now coeffect) to obtain current datetime ... )))
 
    Background
    ----------

src/re_frame/fx.cljc

@@ -15,28 +15,29 @@
 (assert (re-frame.registrar/kinds kind))
 
 (defn reg-fx
-  "Register the given effect `handler` for the given effect `id`.
+  "Register the given effect `handler` for the given `id`.
 
   `id` is keyword, often namespaced.
-  `handler` is a side-effecting function which takes a single value and returns nothing.
+  `handler` is a side-effecting function which takes a single argument and whose return
+  value is ignored.
 
   Example Use
   -----------
 
-  First registration ... associating `:effect2` with a handler.
+  First, registration ... associate `:effect2` with a handler.
 
   (reg-fx
      :effect2
      (fn [value]
         ... do something side-effect-y))
 
-  Then, later if an event handler were to return this effects map:
+  Then, later, if an event handler were to return this effects map ...
 
-  {:effect1  42
+  {...
    :effect2  [1 2]}
 
-   Then the `handler` `fn` we registered previously, using reg-fx, will be
-   called with a `value` argument of `[1 2]`."
+   ... then the `handler` `fn` we registered previously, using `reg-fx`, will be
+   called with an argument of `[1 2]`."
   [id handler]
   (register-handler kind id handler))