 (ns lambdacd.steps.manualtrigger
+  "Build step that waits for manual user interaction.
+
+  Example:
+  ```clojure
+  > (wait-for-manual-trigger args ctx) ; Blocks, but setting `:trigger-id` in step-result to a random UUID
+  > (post-id ctx trigger-id trigger-parameters) ; Returns immediately, unblocks the waiting manual trigger
+  ```
+  "
   (:require [clojure.core.async :as async]
             [clojure.tools.logging :as log]
             [lambdacd.event-bus :as event-bus]
             [lambdacd.steps.support :as support])
   (:import (java.util UUID)))
 
-(defn post-id [ctx id trigger-parameters]
+(defn post-id
+  "Entrypoint for UI and others to release a waiting trigger identified by an ID."
+  [ctx id trigger-parameters]
   (log/info "received parameterized trigger with id " id " with data " trigger-parameters)
   (event-bus/publish!! ctx :manual-trigger-received {:trigger-id         id
                                                    :trigger-parameters trigger-parameters}))

        _              (event-bus/unsubscribe ctx :manual-trigger-received subscription)]
    wait-result))

(defn parameterized-trigger [parameter-config ctx]
  (async/>!! (:result-channel ctx) [:parameters parameter-config])
  (wait-for-manual-trigger nil ctx))

          (recur))))))

(defn ^{:display-type :manual-trigger} wait-for-manual-trigger
  "Build step that waits for someone to trigger a build manually, usually by clicking a button in a UI that supports it."
  [_ ctx & _]
  (let [trigger-id     (str (UUID/randomUUID))
        result-ch      (:result-channel ctx)
