   {:author "James Elliott"}
   (:require [com.evocomputing.colors :as colors]))
 
-(defn channel [offset]
+(defn channel
+  "Creates a minimal channel specification, containing just the
+  address offset within the fixture's list of channels. The first
+  channel used by a fixture is, by convention, given offset 1.
+
+  You probably want to use [[fine-channel]] rather than this function
+  to create even channels which do not have a `:fine-offset` because
+  of the other helpful features it offers, such as setting up the
+  channel function specification for you."
+  {:doc/format :markdown}
+  [offset]
   {:offset offset})
 
 (defn- assign-channel [universe start-address raw-channel]

   (fine-channel :dimmer offset :fine-offset fine-offset :range-label "Intensity")))

(defn color
  "A channel which controls a color component, with an optional second
  channel for fine control."
  [offset color & {:keys [hue function-label fine-offset]}]
  {:pre (some? color)}
  (let [color (keyword color)]

         :fixture fixture :id (id-fn)))

(defn- patch-heads
  "Assigns the heads of a fixture to a DMX universe and starting
  channel; resolves all of their channel assignments."
  [fixture channel-assigner id-fn]
  (let [assigner (partial patch-head channel-assigner fixture id-fn)]
    (update-in fixture [:heads] #(map assigner %))))

(defn patch-fixture
  "Assign a fixture to a DMX universe and starting channel; resolves
  all of its channel assignments."
  [fixture universe start-address id-fn]
  (let [assigner (partial assign-channel universe start-address)]
    (update-in (patch-heads fixture assigner id-fn) [:channels] #(map assigner %))))
