             (adjust-phase (rhythm/snapshot-phrase-phase snapshot phrase-ratio) phase)))))
 
 (defn triangle-beat
-  "Returns an oscillator which generates a triangle wave relative to the phase
-  of the current beat. Supplying a beat ratio will run the oscillator at
-  the specified fraction or multiple of a beat, and supplying a phase
-  will offset the oscillator from the underlying metronome phase by that
-  amount."
+  "Returns an oscillator which generates a triangle wave relative to
+  the phase of the current beat. Supplying a value with `:beat-ratio`
+  will run the oscillator at the specified fraction or multiple of a
+  beat, and supplying a `:phase` will offset the oscillator from the
+  underlying metronome phase by that amount. (See the
+  [documentation](https://github.com/brunchboy/afterglow/blob/master/doc/oscillators.adoc#triangle-oscillators)
+  for an expanded explanation illustrated with graphs.)"
+  {:doc/format :markdown}
   [& {:keys [beat-ratio phase] :or {beat-ratio 1 phase 0.0}}]
   (fn [^afterglow.rhythm.MetronomeSnapshot snapshot]
     (let [reached (adjust-phase (rhythm/snapshot-beat-phase snapshot beat-ratio) phase)]

        (- 2.0 (* reached 2.0))))))

(defn triangle-phrase
  "Returns an oscillator which generates a triangle wave relative to the phase
  of the current phrase. Supplying a phrase ratio will run the oscillator at
  the specified fraction or multiple of a phrase, and supplying a phase
  will offset the oscillator from the underlying metronome phase by that
  amount."
  [& {:keys [phrase-ratio phase] :or {phrase-ratio 1 phase 0.0}}]
  (fn [^afterglow.rhythm.MetronomeSnapshot snapshot]
    (let [reached (adjust-phase (rhythm/snapshot-phrase-phase snapshot phrase-ratio) phase)]


(defn sawtooth-phrase
  "Returns an oscillator which generates a sawtooth wave relative to the phase
  of the current phrase. Passing `true` with `:down?` creates an inverse sawtooth wave
  (ramps downward rather than upward), supplying a value with
  `:phrase-ratio` will run the oscillator at the specified fraction or
  multiple of a phrase, and supplying a `:phase` will offset the
  oscillator from the underlying metronome phase by that amount. (See the
  [documentation](https://github.com/brunchboy/afterglow/blob/master/doc/oscillators.adoc#sawtooth-oscillators)
  for an expanded explanation illustrated with graphs.)"
  {:doc/format :markdown}
  [& {:keys [down? phrase-ratio phase] :or {down? false phrase-ratio 1 phase 0.0}}]
  (cond (and (= phrase-ratio 1) (= phase 0.0))  ; Simplest case, maybe no calculation
        (if down?
