Further work on "API docs". Promise more nudity.

src/re_frame/core.cljc

@@ -16,19 +16,31 @@
     [clojure.set               :as set]))
 
 
-;; XXX move API functions up to this core level - to enable code completion and auto-generated docs
+;; This namespace defines the re-frame API
+
+;; When originally writing this re-frame API namespace, we used
+;; this technique:
+;;    (def api-name (deeper.namespace/where-the-defn-is))
+;;
+;; Turns out this technique makes it hard:
+;;   - to auto-generate API docs
+;;   - for IDEs to provide code completion on functions in the API.
+;;
+;; Which is annoying. But there are pros and cons and we haven't yet
+;; revisited the decision. So, sorry, in advance. To compensate we've
+;; added more nudity to the official docs.
 
 
 ;; --  dispatch ---------------------------------------------------------------
-(def dispatch         router/dispatch)
-(def dispatch-sync    router/dispatch-sync)
+(def dispatch       router/dispatch)
+(def dispatch-sync  router/dispatch-sync)
 
 
 ;; --  subscriptions ----------------------------------------------------------
-(def reg-sub             subs/reg-sub)
-(def subscribe           subs/subscribe)
+(def reg-sub        subs/reg-sub)
+(def subscribe      subs/subscribe)
 
-(def clear-sub    (partial registrar/clear-handlers subs/kind))
+(def clear-sub (partial registrar/clear-handlers subs/kind))  ;; think unreg-sub
 (def clear-subscription-cache! subs/clear-subscription-cache!)
 
 (defn reg-sub-raw
@@ -41,49 +53,67 @@
 
 ;; -- effects -----------------------------------------------------------------
 (def reg-fx      fx/register)
-(def clear-fx    (partial registrar/clear-handlers fx/kind))
+(def clear-fx    (partial registrar/clear-handlers fx/kind))  ;; think unreg-fx
 
 ;; -- coeffects ---------------------------------------------------------------
 (def reg-cofx    cofx/register)
 (def inject-cofx cofx/inject-cofx)
-(def clear-cofx (partial registrar/clear-handlers cofx/kind))
+(def clear-cofx (partial registrar/clear-handlers cofx/kind)) ;; think unreg-cofx
 
 
 ;; --  Events -----------------------------------------------------------------
-(def clear-event (partial registrar/clear-handlers events/kind))
 
 (defn reg-event-db
-  "Register the given `id`, typically a namespaced keyword, with the combination of
-  `db-handler` and an interceptor chain.
-  `db-handler` is a function: (db event) -> db
-  `interceptors` is a collection of interceptors, possibly nested (needs flattening).
-  `db-handler` is wrapped in an interceptor and added to the end of the chain, so
-   that, in the end, there is only a chain.
-   The necessary effects and coeffects handler are added to the front of the
-   interceptor chain.  These interceptors ensure that app-db is available and updated."
-  ([id db-handler]
-    (reg-event-db id nil db-handler))
-  ([id interceptors db-handler]
-   (events/register id [cofx/inject-db fx/do-fx interceptors (db-handler->interceptor db-handler)])))
+  "Register the given event `handler` (function) for the given `id`. Optionally, provide
+  an `interceptors` chain.
+  `id` is typically a namespaced keyword  (but can be anything)
+  `handler` is a function: (db event) -> db
+  `interceptors` is a collection of interceptors. Will be flattened and nils removed.
+  `handler` is wrapped in its own interceptor and added to the end of the interceptor
+   chain, so that, in the end, only a chain is registered.
+   Special effects and coeffects interceptors are added to the front of this
+   chain."
+  ([id handler]
+    (reg-event-db id nil handler))
+  ([id interceptors handler]
+   (events/register id [cofx/inject-db fx/do-fx interceptors (db-handler->interceptor handler)])))
 
 
 (defn reg-event-fx
-  ([id fx-handler]
-   (reg-event-fx id nil fx-handler))
-  ([id interceptors fx-handler]
-   (events/register id [cofx/inject-db fx/do-fx interceptors (fx-handler->interceptor fx-handler)])))
+  "Register the given event `handler` (function) for the given `id`. Optionally, provide
+  an `interceptors` chain.
+  `id` is typically a namespaced keyword  (but can be anything)
+  `handler` is a function: (coeffects-map event-vector) -> effects-map
+  `interceptors` is a collection of interceptors. Will be flattened and nils removed.
+  `handler` is wrapped in its own interceptor and added to the end of the interceptor
+   chain, so that, in the end, only a chain is registered.
+   Special effects and coeffects interceptors are added to the front of the
+   interceptor chain.  These interceptors inject the value of app-db into coeffects,
+   and, later, action effects."
+  ([id handler]
+   (reg-event-fx id nil handler))
+  ([id interceptors handler]
+   (events/register id [cofx/inject-db fx/do-fx interceptors (fx-handler->interceptor handler)])))
 
 
 (defn reg-event-ctx
+  "Register the given event `handler` (function) for the given `id`. Optionally, provide
+  an `interceptors` chain.
+  `id` is typically a namespaced keyword  (but can be anything)
+  `handler` is a function: (context-map event-vector) -> context-map
+
+  This form of registration is almost never used. "
   ([id handler]
    (reg-event-ctx id nil handler))
   ([id interceptors handler]
    (events/register id [cofx/inject-db fx/do-fx interceptors (ctx-handler->interceptor handler)])))
 
+(def clear-event (partial registrar/clear-handlers events/kind)) ;; think unreg-event-*
 
 ;; -- interceptors ------------------------------------------------------------
 
-;; Standard interceptors. Detailed docs in std-interceptors.cljs
+;; Standard interceptors.
+;; Detailed docs on each in std-interceptors.cljs
 (def debug       std-interceptors/debug)
 (def path        std-interceptors/path)
 (def enrich      std-interceptors/enrich)
@@ -92,9 +122,9 @@
 (def on-changes  std-interceptors/on-changes)
 
 
-;; utility functions - for creating your own interceptors
+;; Utility functions for creating your own interceptors
 ;;
-;;  (def some-interceptor
+;;  (def my-interceptor
 ;;     (->interceptor                ;; used to create an interceptor
 ;;       :id     :my-interceptor     ;; an id - decorative only
 ;;       :before (fn [context]                         ;; you normally want to change :coeffects
@@ -124,8 +154,8 @@
 ;; If you are writing an extension to re-frame, like perhaps
 ;; an effects handler, you may want to use re-frame logging.
 ;;
-;; usage:  (console :error "this is bad: " a-variable " and " anotherv)
-;;         (console :warn "possible breach of containment wall at: " dt)
+;; usage: (console :error "Oh, dear God, it happened: " a-var " and " another)
+;;        (console :warn "Possible breach of containment wall at: " dt)
 (def console loggers/console)