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

        0.0))))

(defn square-bar
  "Returns an oscillator which generates a square wave relative to the phase
  of the current bar. Specifying a width adjusts how much of the time the
  wave is on (high); the default is 0.5, lower values cause it to turn on
  sooner, larger values later. In any case the width must be greater than
  0.0 and less than 1.0. Supplying a bar ratio will run the oscillator at
  the specified fraction or multiple of a bar, and supplying a phase
  will offset the oscillator from the underlying metronome phase by that
  amount. "
  [& {:keys [width bar-ratio phase] :or {width 0.5 bar-ratio 1 phase 0.0}}]
  (when-not (and (> width 0.0) (< width 1.0))
    (throw (IllegalArgumentException. "width must fall between 0.0 and 1.0")))

      (+ 0.5 (Math/sin (* two-pi (adjust-phase (rhythm/snapshot-beat-phase snapshot beat-ratio) adjusted-phase)))))))

(defn sine-bar
  "Returns an oscillator which generates a sine wave relative to the
  phase of the current bar. The wave has value `0.0` at phase `0.0`,
  rising to `1.0` at phase `0.5`, and returning to `0.0`. Supplying a
  value with `:bar-ratio` will run the oscillator at the specified
  fraction or multiple of a bar, 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#sine-oscillators)
  for an expanded explanation illustrated with graphs.)"
  {:doc/format :markdown}
  [& {:keys [bar-ratio phase] :or {bar-ratio 1 phase 0.0}}]
  (let [adjusted-phase (- phase 0.25)
        two-pi (* 2.0 Math/PI)]
