     (history-entry build-number (state/get-step-results ctx build-number) (state/get-build-metadata ctx build-number))))
 
 (defn history-for
-  "Returns a build history for a given build state (the result of get-all) or a ctx;
-  Calling this with a complete build state (the get-all-result) is now DEPRECATED"
+  "Returns a build history for a given ctx;
+  Calling this with a complete build state (the get-all-result) is now DEPRECATED.
+
+  Example:
+  ```clojure
+  > (history-for ctx)
+  [{:build-number          8
+    :status                :waiting
+    :most-recent-update-at stop-time
+    :first-updated-at      start-time
+    :retriggered           nil
+    :duration-in-sec       10
+    :build-metadata {:some :metadata}}
+   {:build-number          9
+    :status                :running
+    :most-recent-update-at stop-time
+    :first-updated-at      start-time
+    :retriggered           2
+    :duration-in-sec       10
+    :build-metadata {}}]
+  ```"
   [all-state-or-ctx]
   (if (:pipeline-state-component all-state-or-ctx)
     (history-for-pipeline-state-component all-state-or-ctx)
     (legacy-history-for all-state-or-ctx)))
 
-(defn most-recent-step-result-with [key ctx]
+(defn most-recent-step-result-with
+  "Searches the build history for the current build-step (as denoted by the `:step-id` in `ctx`) for a step result with a particular key and returns the complete step result."
+  [key ctx]
   (->> (state/all-build-numbers ctx)
        (reverse)
        (map #(state/get-step-result ctx % (:step-id ctx)))

(defn- interval-duration [interval]
  (t/in-seconds interval))

(defn build-duration [step-ids-and-results]
  (->> step-ids-and-results
       (vals)
       (filter not-waiting?)

(defn- step-result [[_ step-result]]
  step-result)

(defn overall-build-status
  "Takes a map of step-ids to step results and returns the status of the pipeline as a whole:
  ```clojure
  > (overall-build-status {'(0) {:status :success :most-recent-update-at stop-time :first-updated-at start-time}
                           '(1) {:status :running :most-recent-update-at stop-time :first-updated-at start-time}})
  :running
  ```"
  [step-ids-and-results]
  (let [accumulated-status (->> step-ids-and-results
                                (filter root-step?)
                                (sort-by root-step-id)
