           (get possible-state-transitions $)
           (contains? $ s))))
 
+(alter-meta! #'->JobExecution assoc :no-doc true)
+(alter-meta! #'map->JobExecution assoc :no-doc true)
+
 (defn job-execution?
   "Check if `obj` is a job execution"
   [obj]
   (instance? JobExecution obj))
 
 (defn make-job-execution
-  [context]
-  (map->JobExecution {:context context
+  "Create a new job execution and make it owner of the job execution
+  context `ctx`."
+  [ctx]
+  (map->JobExecution {:context ctx
                       :state ::created}))
 (defn created?
+  "Check if `job-exec`s state is *created*."
   [^JobExecution job-exec]
   (= ::created (sm/current-state job-exec)))
 
 (defn mark-queued
+  "Mark `job-exec` as *queued*."
   [^JobExecution job-exec]
   (sm/transition-to-state job-exec ::queued))
 
 (defn queued?
+  "Check if `job-exec`s state is *queued*."
   [^JobExecution job-exec]
   (= ::queued (sm/current-state job-exec)))
 
 (defn update-context
-  "Apply the function `f` job the job execuction `job-exec`'s
-  job execution context and replace the old context with the new one.
-  `f` must return another job execution context."
+  "Apply the function `f` job the job execuction `job-exec`'s job execution
+  context. Replace the old context with the new one returned by `f`."
   [^JobExecution job-exec f & args]
   (letfn [(apply-f [ctx]
             {:post [(ex-ctx/job-execution-context? %)]}

    (update-in job-exec [:context] apply-f)))

(defn mark-executing
  [^JobExecution job-exec]
  (as-> job-exec $
        (update-context $ ex-ctx/mark-executing)
        (sm/transition-to-state $ ::executing)))

(defn executing?
  [^JobExecution job-exec]
  (= ::executing (sm/current-state job-exec)))

(defn mark-finished
  [^JobExecution job-exec]
  (letfn [(update-ctx [ctx] (if (ex-ctx/failed? ctx)
                              ctx

                                    (keys)
                                    (set)))

(defrecord ^{:no-doc true} JobExecution [state context]

  sm/Stateful
  (current-state [^JobExecution this] (:state this))
