         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. "
+  "Returns an oscillator which generates a square wave relative to the
+  phase of the current bar. 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 `: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#square-oscillators)
+  for an expanded explanation illustrated with graphs.)"
+  {:doc/format :markdown}
   [& {: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.0))))

(defn square-phrase
  "Returns an oscillator which generates a square wave relative to the phase
  of the current phrase. 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 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 [width phrase-ratio phase] :or {width 0.5 phrase-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")))

        (- 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 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#triangle-oscillators)
  for an expanded explanation illustrated with graphs.)"
  {:doc/format :markdown}
  [& {: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)]
