Ensure coherent style on docstrings

src/moira/application.cljs

@@ -52,9 +52,10 @@
     Returns a `Promise` that resolves to the updated `system-map`."))
 
 (defprotocol Transitionable
-  "Manage the lifecycle of an [[Application]] through chained updates. The
-  [[moira.transition]] is guaranteed to be applied on module dependencies first
-  for [[up!]] and last for [[down!]]."
+  "Manage the lifecycle of an [[Application]] through chained updates.
+
+  The [[moira.transition]] is guaranteed to be applied on module dependencies
+  first for [[up!]] and last for [[down!]]."
 
   (up! [this txs ks]
     "Update `this` by elevating modules defined for `ks` and all their
@@ -114,8 +115,8 @@
     Returns a `Promise` that resolves to the updated `system-map`."))
 
 (def ^:dynamic *timeout*
-  "Maximum duration in milliseconds for a [[moira.transition|transition]] to
-  complete.
+  "Configure maximum duration in milliseconds for a
+  [[moira.transition|transition]] to complete.
 
   Lifecycle events should settle swiftly to minimize the period during which
   the system is in a transitional state. If the update is not fulfilled or
@@ -144,8 +145,10 @@
 (deftype
  ^{:doc
    "Construct `Application` instances using [[create]] to properly wrap
-   `system-map`, instrument modules, and initiate state. Avoid using the
-   `->Application` conctructor directly.
+   `system-map`, instrument modules, and initiate state.
+
+   The `->Application` conctructor should never be used by external code
+   directly.
 
    `Application` implements
    [`IDeref`](https://cljs.github.io/api/cljs.core/IDeref),
@@ -264,9 +267,10 @@
   (->Application (atom system-map) (volatile! (p/resolved system-map))))
 
 (defn start!
-  "Start modules defined for `ks` and their dependencies. If `ks` is not
-  provided, start all modules. Returns a `Promise` that resolves to the updated
-  `system-map` after all module states have settled.
+  "Start modules defined for `ks` and their dependencies.
+
+  If `ks` is not provided, start all modules. Returns a `Promise` that resolves
+  to the updated `system-map` after all module states have settled.
 
   Dependencies are started first, so each module's transition is guaranteed to
   be applied before any depending modules. `:app-log` is injected, if not
@@ -292,9 +296,10 @@
         ks)))
 
 (defn stop!
-  "Stop modules defined for `ks`. If `ks` is not provided, stop all modules.
-  Returns a `Promise` that resolves to the updated `system-map` after all
-  module states have settled.
+  "Stop modules defined for `ks`.
+
+  If `ks` is not provided, stop all modules. Returns a `Promise` that resolves
+  to the updated `system-map` after all module states have settled.
 
   Dependencies are not stopped, and order of execution is reversed.
   Consequently, each module's transition is guaranteed to be applied *after*
@@ -321,9 +326,10 @@
           ks)))
 
 (defn pause!
-  "Pause modules defined for `ks`. If `ks` is not provided, pause all modules.
-  Returns a `Promise` that resolves to the updated `system-map` after all
-  module states have settled.
+  "Pause modules defined for `ks`.
+
+  If `ks` is not provided, pause all modules. Returns a `Promise` that resolves
+  to the updated `system-map` after all module states have settled.
 
   Dependencies are not paused, and order of execution is reversed.
   Consequently, each module's transition is guaranteed to be applied *after*
@@ -360,9 +366,10 @@
           ks)))
 
 (defn resume!
-  "Resume modules defined for `ks` and their dependencies. If `ks` is not
-  provided, resume all modules. Returns a `Promise` that resolves to the
-  updated `system-map` after all module states have settled.
+  "Resume modules defined for `ks` and their dependencies.
+
+  If `ks` is not provided, resume all modules. Returns a `Promise` that
+  resolves to the updated `system-map` after all module states have settled.
 
   Dependencies are resumed first, so each module's transition is guaranteed to
   be applied before any depending modules. This is a lightweight
@@ -390,9 +397,10 @@
 
 (defn init!
   "Merge `config` into `app` and start modules defined for `ks` and their
-  dependencies. If `ks` is not provided, start all modules. Returns a `Promise`
-  that resolves to the updated `system-map` after all module states have
-  settled.
+  dependencies.
+
+  If `ks` is not provided, start all modules. Returns a `Promise` that resolves
+  to the updated `system-map` after all module states have settled.
 
       (defn main [api-token]
         (application/init! app {:module-a {:token api-token}})
@@ -416,10 +424,12 @@
    (start! app ks)))
 
 (defn load!
-  "Extend the `app` by adding `modules` and starting them. Merges existing
-  modules without overwriting any values that are already present. Note that
-  the `app` may already be running.  Returns a `Promise` that resolves to the
-  updated `system-map` after all module states have settled.
+  "Extend the `app` by adding `modules` and starting them.
+
+  Merges existing modules without overwriting any values that are already
+  present. Note that the `app` may already be running.  Returns a `Promise`
+  that resolves to the updated `system-map` after all module states have
+  settled.
 
   See [[start!]] for more details on starting modules.
 

src/moira/context.cljs

@@ -1,5 +1,5 @@
 (ns moira.context
-  "Implementation of the [interceptor design
+  "Implement the [interceptor design
   pattern](https://lambdaisland.com/episodes/interceptors-concepts) based on
   asynchronous `Promise` chains.
 
@@ -42,7 +42,7 @@
 (s/def ::txs (s/coll-of ::tx))
 
 (defn done?
-  "Returns true if there are no more pending execution steps for `ctx` within
+  "Return true if there are no more pending execution steps for `ctx` within
   the scope of `n`.
 
   `n` is used to qualify respective `:queue`, `:stack`, and `:error` keys."
@@ -53,7 +53,7 @@
        (empty? (get ctx (keyword n :stack)))))
 
 (defn error?
-  "Returns true, if scope `n` of `ctx` is in `:error` stage.
+  "Return true if scope `n` of `ctx` is in `:error` stage.
 
   `n` is used to qualify respective `:queue`, `:stack`, and `:error` keys."
 
@@ -62,25 +62,25 @@
   (contains? ctx (keyword n :error)))
 
 (defn queue?
-  "Returns true if `x` is an instance of `PersistentQueue`."
+  "Return true if `x` is an instance of `PersistentQueue`."
 
   [x]
 
   (instance? PersistentQueue x))
 
 (defn into-queue
-  "Returns a `PersistentQueue` from `coll` with all `xs` conjoined."
+  "Create a `PersistentQueue` from `coll` with all `xs` conjoined."
 
   [coll xs]
 
   (let [queue (if (queue? coll) coll (into #queue [] coll))]
     (into queue xs)))
 
 (defn enqueue
-  "Schedule interceptors `txs` for execution within scope `n`. Returns an
-  updated `ctx`.
+  "Schedule interceptors `txs` for execution within scope `n`.
 
-  `n` is used to qualify respective `:queue`, `:stack`, and `:error` keys."
+  Returns an updated `ctx`. `n` is used to qualify respective `:queue`,
+  `:stack`, and `:error` keys."
 
   [ctx n txs]
 
@@ -90,9 +90,10 @@
 
 (defn terminate
   "Drop execution of all pending interceptors within scope `n` and immediately
-  switch to exit stage (i.e., `:leave` or `:error`). Returns an updated `ctx`.
+  switch to exit stage (i.e., `:leave` or `:error`).
 
-  `n` is used to qualify respective `:queue`, `:stack`, and `:error` keys."
+  Returns an updated `ctx`. `n` is used to qualify respective `:queue`,
+  `:stack`, and `:error` keys."
 
   [ctx n]
 
@@ -103,9 +104,9 @@
 
 (defn stack
   "Add inteceptors `txs` to the top of the execution stack for scope `n`.
-  Returns an updated `ctx`.
 
-  `n` is used to qualify respective `:queue`, `:stack`, and `:error` keys."
+  Returns an updated `ctx`. `n` is used to qualify respective `:queue`,
+  `:stack`, and `:error` keys."
 
   [ctx n txs]
 
@@ -128,10 +129,10 @@
       (p/catch #(assoc ctx (keyword n :error) (->ex % data)))))
 
 (defn enter-1
-  "Execute next `:enter` step for scope `n`. Returns a `Promise` resolving to
-  the updated `ctx`.
+  "Execute next `:enter` step for scope `n`.
 
-  Fails gracefully, if not applicable. `n` is used to qualify respective
+  Returns a `Promise` resolving to the updated `ctx`. Fails gracefully, if not
+  applicable. `n` is used to qualify respective
   `:queue`, `:stack`, and `:error` keys."
 
   [ctx n]
@@ -146,10 +147,10 @@
       (p/resolved ctx))))
 
 (defn leave-1
-  "Execute next `:leave` or `:error` step for scope `n`. Returns a `Promise`
-  resolving to the updated `ctx`.
+  "Execute next `:leave` or `:error` step for scope `n`.
 
-  Fails gracefully, if not applicable. `n` is used to qualify respective
+  Returns a `Promise` resolving to the updated `ctx`. Fails gracefully, if not
+  applicable. `n` is used to qualify respective
   `:queue`, `:stack`, and `:error` keys."
 
   [ctx n]
@@ -165,11 +166,11 @@
       (p/resolved ctx))))
 
 (defn execute-1
-  "Execute next `:enter`, `:leave`, or `:error` step for scope `n`. Returns a
-  `Promise` resolving to the updated `ctx`.
+  "Execute next `:enter`, `:leave`, or `:error` step for scope `n`.
 
-  Fails gracefully, if not applicable. `n` is used to qualify respective
-  `:queue`, `:stack`, and `:error` keys."
+  Returns a `Promise` resolving to the updated `ctx`. Fails gracefully, if not
+  applicable. `n` is used to qualify respective `:queue`, `:stack`, and
+  `:error` keys."
 
   [ctx n]
 
@@ -179,11 +180,11 @@
     :else (p/resolved ctx)))
 
 (defn execute-all
-  "Execute all `:enter`, `:leave`, or `:error` steps for scope `n`. Returns a
-  `Promise` resolving to the updated `ctx`.
+  "Execute all `:enter`, `:leave`, or `:error` steps for scope `n`.
 
-  Fails gracefully, if not applicable. `n` is used to qualify respective
-  `:queue`, `:stack`, and `:error` keys."
+  Returns a `Promise` resolving to the updated `ctx`. Fails gracefully, if not
+  applicable. `n` is used to qualify respective `:queue`, `:stack`, and
+  `:error` keys."
 
   [ctx n]
 
@@ -196,12 +197,11 @@
   (if (error? ctx n) (p/rejected (get ctx (keyword n :error))) ctx))
 
 (defn execute
-  "Apply a chain of interceptors `txs` to `ctx` within scope `n`. Returns a
-  `Promise` resolving to the updated context.
+  "Apply a chain of interceptors `txs` to `ctx` within scope `n`.
 
-  `ctx` can be a plain map and will be elevated to be an executable context by
-  enqueueing `txs`. `n` is used to qualify respective `:queue`, `:stack`, and
-  `:error` keys."
+  Returns a `Promise` resolving to the updated context. `ctx` can be a plain
+  map and will be elevated to be an executable context by enqueueing `txs`. `n`
+  is used to qualify respective `:queue`, `:stack`, and `:error` keys."
 
   [ctx n txs]
 

src/moira/module.cljs

@@ -32,8 +32,10 @@
   (s/map-of any? ::module))
 
 (defn ex-cyclic-deps
-  "Returns an error with specific type and data for when a cyclic dependency
-  was detected."
+  "Create an instance of `ExceptionInfo` specific to cyclic dependency errors.
+
+  `k` is the module name in the `system-map`. `visited` is the set of
+  previously addressed dependencies while walking the dependency graph."
 
   [k visited]
 
@@ -43,11 +45,11 @@
             :cycle visited}))
 
 (defn ex-cyclic-deps?
-  "Test helper for checking on error created by [[ex-cyclic-deps]]."
+  "Return true if `ex` was created by [[ex-cyclic-deps]]."
 
-  [e]
+  [ex]
 
-  (= ::cycle-detected (:type (ex-data e))))
+  (= ::cycle-detected (:type (ex-data ex))))
 
 (defn postwalk-deps
   "Get the chain of dependencies for module `k`, depth-first and post-order.
@@ -68,7 +70,7 @@
     (walk k #{})))
 
 (defn dependency-chain
-  "Returns a lazy sequence of modules `ks` and all their dependencies, without
+  "Make a lazy sequence of modules `ks` and all their dependencies, without
   duplicates and in the order of the dependency graph.
 
   `app` must be a `system-map` including all relevant module definitions.
@@ -80,7 +82,9 @@
   (sequence (comp (mapcat (partial postwalk-deps app)) (distinct)) ks))
 
 (def ^:private n
-  "Corresponding interceptors operate on a qualified `::queue` and `::stack`
+  "Namespace name as string.
+
+  Corresponding interceptors operate on a qualified `::queue` and `::stack`
   scoped to this namespace."
 
   (namespace ::_))
@@ -123,7 +127,7 @@
     (apply merge-with #(%2 %1) module* plugins)))
 
 (defn exports
-  "Returns a map of module `ks` to exports.
+  "Make a map of module `ks` to exports.
 
   Each export is the result of applying the respective module's `:export`
   function on the module's current `:state`. `:export` must be free of
@@ -140,9 +144,11 @@
           ks))
 
 (defn step
-  "Returns an [[moira.context|interceptor]] that updates the `::current`
+  "Make an [[moira.context|interceptor]] that updates the `::current`
   module's state by applying the function returned from calling `f` on the
-  module. Typically,`f` will be a keyword, but it can be any function.
+  module.
+
+  Typically,`f` will be a keyword, but it can be any function.
 
   The update function receives the module's current `:state`, [[exports]] from
   dependencies, the module key defined in the `system-map`, and any additional
@@ -170,9 +176,10 @@
                 ctx)))})
 
 (defn enter
-  "Returns an [[moira.context|interceptor]] that terminates execution if `k` is
-  already present in the `::current` module's `:tags`. Updates `:tags` to
-  contain `k` on leave.
+  "Make an [[moira.context|interceptor]] that terminates execution if `k` is
+  already present in the `::current` module's `:tags`.
+
+  Updates `:tags` to contain `k` on leave.
 
   This can be used to ensure a transition like
   [[moira.application/start!|start!]] is only applied once on modules that are
@@ -197,9 +204,10 @@
       (not (contains? tags k)) terminate)))
 
 (defn exit
-  "Returns an [[moira.context|interceptor]] that terminates execution if `k` is
-  *not* present in the `::current` module's `:tags`. Updates `:tags` to no
-  longer contain `k` on leave.
+  "Make an [[moira.context|interceptor]] that terminates execution if `k` is
+  *not* present in the `::current` module's `:tags`.
+
+  Updates `:tags` to no longer contain `k` on leave.
 
   This can be used to ensure a transition like
   [[moira.application/stop!|stop!]] is only applied for modules that are
@@ -216,8 +224,10 @@
                        k))})
 
 (defn only
-  "Returns an [[moira.context|interceptor]] that terminates execution if `k` is
-  not present in `:tags`. Does not update `:tags`.
+  "Make an [[moira.context|interceptor]] that terminates execution if `k` is
+  not present in `:tags`.
+
+  Does not update `:tags`.
 
   This can be used to ensure a transition like
   [[moira.application/pause!|pause!]] is only applied to modules that are