 ;; so they can be scaled in time too. Eventually allow randomization of fade time and perhaps
 ;; hue and peak brightness, with control over how much they vary?
 (defn sparkle
-  "A random sparkling effect like a particle generator over the supplied fixture heads."
+  "A random sparkling effect like a particle generator over the
+  supplied fixture heads.
+
+  As each frame of DMX values generated, each participating fixture
+  head has a chance of being assigned a sparkle (this chance is
+  controlled by the optional keyword parameter `:chance`). Once a
+  sparkle has been created, it will fade out over the number of
+  milliseconds specified by the optional keyword parameter
+  `:fade-time`. The initial color of each sparkle can be changed with
+  the optional keyword parameter `:color`."
+  {:doc/format :markdown}
   [fixtures & {:keys [color chance fade-time] :or {color default-sparkle-color chance 0.001 fade-time 500}}]
   {:pre [(some? *show*)]}
   (let [color (params/bind-keyword-param color :com.evocomputing.colors/color default-sparkle-color)

           (afterglow.rhythm Metronome)
           (javax.vecmath Point3d)))

(def default-down-beat-color
  "The default color to flash on the down beats."
  (colors/lighten (colors/create-color :red) 20))

(def default-other-beat-color
  "The default color to flash on beats that are not down beats."
  (colors/darken (colors/create-color :yellow) 30))

(defn metronome-effect
  "Returns an effect which flashes the supplied fixtures to the beats
  of the show metronome, emphasizing the down beat, which is a great
  way to test and understand metronome synchronization. The color of
  the flashes can be controlled by the :down-beat-color
  and :other-beat-color arguments (defaulting to red with lightness
  70, and yellow with lightness 20, respectively).

  This is no longer as useful as it used to be before there were
  metronome adjustment interfaces in the Ableton Push and then web
  interfaces."
  [fixtures & {:keys [down-beat-color other-beat-color metronome]
               :or {down-beat-color default-down-beat-color
                    other-beat-color default-other-beat-color

  value of 0 will change as soon as transition has started, and the
  fixture(s) that return the largest value will change when the
  transition ends. A value halfway between zero and the largest value
  would mean the color of that fixture or head would change exactly at
  the midpoint of the transition. Many interesting looking
  transtitions can be created using distance measures constructed by
  calling [[afterglow.transform/build-distance-measure]], as is done
