API docs are now complete. Probably still some editing to do.

CHANGES.md

@@ -1,28 +1,28 @@
-## Unreleased
+## Unreleased 0.10.0  (2017.07.NN)
 
-#### New
+#### New Docs
 
-  - added [an API document](/docs/API.md)
+  - added [API documentation](/docs/API.md)
   - added [testing docs](/docs/Testing.md)
   - added [a new mental model](/docs/MentalModelOmnibus.md#on-dsls-and-machines)
   - added [a new FAQ entry](docs/FAQs/When-Does-Dispatch-Happen.md) on dispatch processing 
-  - The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5)
 
-#### Breaking 
+#### Breaking
 
   - [#357](https://github.com/Day8/re-frame/pull/357)
     I'd be amazed if this actually broke any apps. Shocked! But, better safe than sorry. 
-    The effect handler for `:db` has changed: if the value provided tests 
+    The effect handler for `:db` has changed: if the new value provided tests
     `identical?` to the existing value within `app-db`, then `app-db` is not `reset!`. 
-    Previously, `app-db` was always `reset!` when a `:db` effect was supplied, 
+    Previously, `app-db` was always `reset!` irrespective, 
-    which caused Layer 2 subscriptions to run unnecessarily. So this is a tiny 
+    which potentially caused Layer 2 subscriptions to run unnecessarily. So this is a tiny 
-    efficiency change in an edge case, which also results in behaviour that better matches 
+    efficiency change in this edge case, and it results in behaviour that better matches 
     programmer intuitions.
 
 #### Minor Fixes and Improvements
 
+ - The effect handler for `:dispatch-n` will now ignore `nils`. [See checkin](https://github.com/Day8/re-frame/commit/6efdae438f393f8121a2d6dfbf76db00e6dafbf5)
  - [#340](https://github.com/Day8/re-frame/pull/340)
- - [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.std-interceptors/on-changes` to work even if effect handler does not set `:db`. 
+ - [#341](https://github.com/Day8/re-frame/pull/341) Fix `re-frame.core/on-changes` to work even if event handler does not set `:db`. 
 
  
 ## 0.9.4 (2017.06.01)

docs/API.md

@@ -1,12 +1,14 @@
 ## The re-frame API
 
 Orientation:
-  1. The API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace
+  1. The API is provided by [re-frame.core](/src/re_frame/core.cljc) which means:
-  2. The API is quite small - you'll use less than 10 API functions when writing an app.
+     - you should probably browse this namespace sometime
+     - to use re-frame, you'll have to `require` it
+  2. The API is small. Writing an app, you'll use 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)
-  4. But below are helpful links to the doc strings of often-used API functions 
+  4. But below are links to the doc strings of often-used API functions. 
 
-## Links To API docs
+## Doc Strings For API Functions 
 
 The core API consists of: 
   - [dispatch](/src/re_frame/router.cljc#L229-L239), [dispatch-sync](/src/re_frame/router.cljc#L247-L259). See also [this FAQ](/docs/FAQs/When-Does-Dispatch-Happen.md)
@@ -15,8 +17,8 @@ The core API consists of:
   - [subscribe](/src/re_frame/subs.cljc#L67-L83)
 
 Occasionally, you'll need to use:  
-  - [reg-fx]() XXX
+  - [reg-fx](/src/re_frame/fx.cljc#L17-L39)
-  - [reg-cofx]() XXX and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73)
+  - [reg-cofx](/src/re_frame/cofx.cljc#L14-L21) and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73)
      
 And, finally, there are builtin Interceptors which are useful:
   - [path](/src/re_frame/std_interceptors.cljc#L149-L173)
@@ -25,11 +27,11 @@ And, finally, there are builtin Interceptors which are useful:
   - [and browse the others](/src/re_frame/std_interceptors.cljc)
   
 
-### Built-in Effect Handlers
+## Built-in Effect Handlers
 
-The following built-in effects are effectively part of the API:  
+The following built-in effects are part of the API:  
 
-#### :dispatch-later
+### :dispatch-later
 
 `dispatch` one or more events after given delays. Expects a collection
 of maps with two keys: `:ms` and `:dispatch`
@@ -51,7 +53,7 @@ usage:
 {:dispatch [:event-id "param"] }
 ```
 
-#### :dispatch-n
+### :dispatch-n
 
 `dispatch` more than one event. Expects a collection events.
 
@@ -60,7 +62,7 @@ usage:
 {:dispatch-n (list [:do :all] [:three :of] [:these])}
 ```
 
-#### :deregister-event-handler
+### :deregister-event-handler
 
 removes a previously registered event handler. Expects either a single id (
 typically a keyword), or a seq of ids.
@@ -74,7 +76,7 @@ or:
 {:deregister-event-handler [:one-id :another-id]}
 ```
 
-#### :db
+### :db
 
 reset! app-db with a new value. Expects a map. 
 
@@ -83,6 +85,7 @@ usage:
 {:db  {:key1 value1 :key2 value2}}
 ```
 
+*** 
 
 Previous:  [First Code Walk-Through](CodeWalkthrough.md)      
 Up:  [Index](README.md)      

src/re_frame/cofx.cljc

@@ -12,7 +12,13 @@
 (assert (re-frame.registrar/kinds kind))
 
 (defn reg-cofx
-  ""
+  "Register the given coeffect `handler` for the given coeffect `id`.
+
+  `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`.
+
+  Please see the docs for `inject-cofx` for example use."
   [id handler]
   (register-handler kind id handler))
 

src/re_frame/core.cljc

@@ -57,7 +57,7 @@
 
 
 ;; -- effects -----------------------------------------------------------------
-(def reg-fx      fx/register)
+(def reg-fx      fx/reg-fx)
 (def clear-fx    (partial registrar/clear-handlers fx/kind))  ;; think unreg-fx
 
 ;; -- coeffects ---------------------------------------------------------------

src/re_frame/fx.cljc

@@ -13,22 +13,51 @@
 
 (def kind :fx)
 (assert (re-frame.registrar/kinds kind))
-(def register  (partial register-handler kind))
+
+(defn reg-fx
+  "Register the given effect `handler` for the given effect `id`.
+
+  `id` is keyword, often namespaced.
+  `handler` is a side-effecting function which takes a single value and returns nothing.
+
+  Example Use
+  -----------
+
+  First registration ... associating `: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:
+
+  {: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]`."
+  [id handler]
+  (register-handler kind id handler))
 
 ;; -- Interceptor -------------------------------------------------------------
 
 (def do-fx
-  "An interceptor whose `:after` executes the instructions in `:effects`.
+  "An interceptor whose `:after` actions the contents of `:effects`. As a result,
+  this interceptor is Domino 3.
+
+  This interceptor is silently added (by reg-event-db etc) to the front of
+  interceptor chains for all events.
 
   For each key in `:effects` (a map), it calls the registered `effects handler`
-  (see `reg-fx` for registration of effects handlers).
+  (see `reg-fx` for registration of effect handlers).
 
   So, if `:effects` was:
       {:dispatch  [:hello 42]
        :db        {...}
        :undo      \"set flag\"}
 
-  it will call the registered effects handlers for each of the map's keys:
+  it will call the registered effect handlers for each of the map's keys:
   `:dispatch`, `:undo` and `:db`. When calling each handler, provides the map
   value for that key - so in the example above the effect handler for :dispatch
   will be given one arg `[:hello 42]`.