Still working on API docs - move "built-in effects docs"

docs/API.md

@@ -1,13 +1,14 @@
 ## The re-frame API
 
 Orientation:
-  1. The re-frame API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace
+  1. The API is provided by the [re-frame.core](/src/re_frame/core.cljc) namespace
-  2. Typically, you'll only use 4 to 10 of the API functions (small surface)  
+  2. The API is quite small - you'll use less than 10 API functions when writing an app.
-  3. Oft-used API functions have doc strings, linked-to below (no auto-generated docs [because of this problem](/src/re_frame/core.cljc#L23-L36))
+  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 
 
 ## Links To API docs
 
-The core API is: 
+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)
   - [reg-event-db](/src/re_frame/core.cljc#L71-L80), [reg-event-fx](/src/re_frame/core.cljc#L87-L97) 
   - [reg-sub](/src/re_frame/subs.cljc#L151-L237)
@@ -17,17 +18,71 @@ Occasionally, you'll need to use:
   - [reg-fx]() XXX
   - [reg-cofx]() XXX and [inject-cofx](/src/re_frame/cofx.cljc#L22-L73)
      
-And, finally, there are builtin Interceptors which are used a bit:
+And, finally, there are builtin Interceptors which are useful:
   - [path](/src/re_frame/std_interceptors.cljc#L149-L173)
   - [after](/src/re_frame/std_interceptors.cljc#L260-L281)
   - [debug](/src/re_frame/std_interceptors.cljc#L13-L36)
   - [and browse the others](/src/re_frame/std_interceptors.cljc)
   
-Builtin effects:
+
-  XXX
+### Built-in Effect Handlers
-  
+
-Builtin coeffects:
+The following built-in effects are effectively part of the API:  
-  XXX
+
+#### :dispatch-later
+
+`dispatch` one or more events after given delays. Expects a collection
+of maps with two keys: `:ms` and `:dispatch`
+
+usage:
+```clj
+{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}    
+                  {:ms 100 :dispatch [:also :this :in :100ms]}]}
+```
+
+Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
+
+#### :dispatch
+
+`dispatch` one event. Expects a single vector.
+
+usage:
+```clj
+{:dispatch [:event-id "param"] }
+```
+
+#### :dispatch-n
+
+`dispatch` more than one event. Expects a collection events.
+
+usage:
+```clj
+{:dispatch-n (list [:do :all] [:three :of] [:these])}
+```
+
+#### :deregister-event-handler
+
+removes a previously registered event handler. Expects either a single id (
+typically a keyword), or a seq of ids.
+
+usage:
+```clj
+{:deregister-event-handler :my-id)}
+```
+or:
+```clj
+{:deregister-event-handler [:one-id :another-id]}
+```
+
+#### :db
+
+reset! app-db with a new value. Expects a map. 
+
+usage:
+```clj
+{:db  {:key1 value1 :key2 value2}}
+```
+
 
 Previous:  [First Code Walk-Through](CodeWalkthrough.md)      
 Up:  [Index](README.md)      

docs/Effects.md

@@ -21,12 +21,6 @@ make side effects a noop in event replays.
 - [Effects With No Data](#effects-with-no-data)
 - [Testing And Noops](#testing-and-noops)
 - [Summary](#summary)
-- [Builtin Effect Handlers](#builtin-effect-handlers)
-  - [:dispatch-later](#dispatch-later)
-  - [:dispatch](#dispatch)
-  - [:dispatch-n](#dispatch-n)
-  - [:deregister-event-handler](#deregister-event-handler)
-  - [:db](#db)
 - [External Effects](#external-effects)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -280,76 +274,21 @@ then you can use a `fixture` to restore all effect handlers at the end of your t
 `re-frame.core/make-restore-fn` creates a checkpoint for re-frame state (including 
 registered handlers) to which you can return. 
 
+### Existing Effect Handlers
+
+Built-in effect handlers are detailed [the API](/docs/API.md) document.
+
+And please review the [External-Resources document](External-Resources.md) for a list of 3rd party Effect Handlers.
+
+
 ### Summary 
 
-The 4 Point Summary
+The 4 Point Summary in note form:
-
-In note form:
 
 1. Event handlers should only return effect declaratively
 2. They return a map like `{:effect1 value1 :effect2 value2}`
 3. Keys of this map can refer to builtin effects handlers (see below) or custom ones
-4. We use `reg-fx` to register our own effects handlers, builtin ones are already registered
+4. We use `reg-fx` to register our own effects handlers, built-in ones are already registered
-
-### Builtin Effect Handlers
-
-#### :dispatch-later
-
-`dispatch` one or more events after given delays. Expects a collection
-of maps with two keys: `:ms` and `:dispatch`
-
-usage:
-```clj
-{:dispatch-later [{:ms 200 :dispatch [:event-id "param"]}    
-                  {:ms 100 :dispatch [:also :this :in :100ms]}]}
-```
-
-Which means: in 200ms do this: `(dispatch [:event-id "param"])` and in 100ms ...
-
-#### :dispatch
-
-`dispatch` one event. Expects a single vector.
-
-usage:
-```clj
-{:dispatch [:event-id "param"] }
-```
-
-#### :dispatch-n
-
-`dispatch` more than one event. Expects a collection events.
-
-usage:
-```clj
-{:dispatch-n (list [:do :all] [:three :of] [:these])}
-```
-
-#### :deregister-event-handler
-
-removes a previously registered event handler. Expects either a single id (
-typically a keyword), or a seq of ids.
-
-usage:
-```clj
-{:deregister-event-handler :my-id)}
-```
-or:
-```clj
-{:deregister-event-handler [:one-id :another-id]}
-```
-
-#### :db
-
-reset! app-db with a new value. Expects a map. 
-
-usage:
-```clj
-{:db  {:key1 value1 :key2 value2}}
-```
-
-### External Effects
-
-Please see the [External-Resources document](External-Resources.md) for a list of 3rd part Effect Handlers.
 
 
 ***