From ed79d8e4ac8bd243e7c6228167fc89c599a984fc Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Thu, 20 Jul 2017 13:40:28 +1000 Subject: [PATCH] Further work on "API docs". Promise more nudity. --- src/re_frame/core.cljc | 90 ++++++++++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 30 deletions(-) diff --git a/src/re_frame/core.cljc b/src/re_frame/core.cljc index 851f56a..4c67e93 100644 --- a/src/re_frame/core.cljc +++ b/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)