         child-step-id  (step-id/child-id parent-step-id child-number)]
     (assoc parent-ctx :step-id child-step-id)))
 
-(defn ^{:display-type :parallel} junction [condition-step success-step failure-step]
+(defn ^{:display-type :parallel} junction
+  "Build step that executes the first child and, depending on its success, the second or third child.
+  Commonly used for conditional, if-then-else logic in pipelines.
+
+  Example:
+  ```clojure
+  (def pipeline-structure
+    `(; ...
+      (junction
+        should-do-something?
+        step-to-run-if-success
+        step-to-run-if-not-success)))
+  ```"
+  [condition-step success-step failure-step]
   (fn [args ctx]
     (post-process-container-results
       (let [condition-step-result (execution/execute-step args (child-context ctx 1) condition-step)]

(ns lambdacd.steps.control-flow
  "control flow elements for a pipeline: steps that control the way their child-steps are being run"
  (:require [lambdacd.execution.core :as execution]
            [clojure.core.async :as async]
            [lambdacd.steps.support :as support]

    (add-watch source key #(reset! target %4))
    key))

(defn ^{:display-type :parallel} either
  "Build step that executes its children in parallel and returns after the first child finished successfully.
  Commonly used to wait for one of multiple triggers to return.

  Example:
  ```clojure
  (def pipeline-structure
    `((either
        wait-for-git-commit
        wait-for-manual-trigger)
      build
      test
      deploy))
  ```
  "
  [& steps]
  (fn [args ctx]
    (let [parent-kill-switch (:is-killed ctx)
          kill-switch        (atom false)
