         _              (event-bus/unsubscribe ctx :manual-trigger-received subscription)]
     wait-result))
 
-(defn parameterized-trigger [parameter-config ctx]
+(defn parameterized-trigger
+  "Same as `wait-for-manual-trigger` but also sets metadata that instructs a supporting UI to ask the user for parameters
+  that will be sent and returned.
+
+  Example:
+  ```clojure
+  > (parameterized-trigger {:version {:desc \"version to deploy\"}} ctx) ; blocks until post-id is called
+  {:status :success
+   :version {:version \"some-version\"}}
+  > (post-id ctx trigger-id {:version \"some-version\"})
+  ```
+  "
+
+  [parameter-config ctx]
   (async/>!! (:result-channel ctx) [:parameters parameter-config])
   (wait-for-manual-trigger nil ctx))

(ns lambdacd.steps.manualtrigger
  (: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]
  (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}))

          (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)
