         (- 2.0 (* reached 2.0))))))
 
 (defn square-beat
-  "Returns an oscillator which generates a square wave relative to the phase
-  of the current beat. 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 off
-  sooner, larger values later. In any case the width must be greater than
-  0.0 and less than 1.0. 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 square wave relative to the
+  phase of the current beat. Specifying a value with `:width` adjusts
+  how much of the time the wave is _on_ (high); the default is `0.5`,
+  lower values cause it to turn off sooner, larger values later. In
+  any case the width must be greater than `0.0` and less than `1.0`.
+  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#square-oscillators)
+  for an expanded explanation illustrated with graphs.)"
+  {:doc/format :markdown}
   [& {:keys [width beat-ratio phase] :or {width 0.5 beat-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 (* 0.5 (Math/sin (* two-pi (adjust-phase (rhythm/snapshot-bar-phase snapshot bar-ratio) adjusted-phase))))))))

(defn sine-phrase
  "Returns an oscillator which generates a sine wave relative to the phase
  of the current phrase. The wave has value 1.0 at phase 0.0, dropping to 0.0
  at phase 0.5, and returning to 1.0. 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}}]
  (let [adjusted-phase (- phase 0.25)
        two-pi (* 2.0 Math/PI)]

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

(defn triangle-bar
  "Returns an oscillator which generates a triangle wave relative to
  the phase of the current bar. 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#triangle-oscillators)
  for an expanded explanation illustrated with graphs.)"
  {:doc/format :markdown}
  [& {:keys [bar-ratio phase] :or {bar-ratio 1 phase 0.0}}]
  (fn [^afterglow.rhythm.MetronomeSnapshot snapshot]
    (let [reached (adjust-phase (rhythm/snapshot-bar-phase snapshot bar-ratio) phase)]
