 
 ;; Sending a synth-id of -1 lets the server choose an ID
 (defn node
-  "Instantiate a synth node on the audio server."
+  "Instantiate a synth node on the audio server.  Takes the synth name and a set of 
+  argument name/value pairs.  Optionally use :target <node/group-id> and :position <pos>
+  to specify where the node should be located.  The position can be one of :head, :tail,
+  :before-node, :after-node, or :replace-node.
+
+  (node \"foo\")
+  (node \"foo\" :pitch 60)
+  (node \"foo\" :pitch 60 :target 0)
+  (node \"foo\" :pitch 60 :target 2 :position :tail)
+  "
   [synth-name & args]
   {:pre [(connected?)]}
   (let [id (alloc-id :node)

             (concat named [(first names) (first args)]))
      named)))

(defn synth-player [sname arg-names]
  (fn [& args]
    (let [[args sgroup] (if (= :target (first args))
                          [(drop 2 args) (second args)]
                          [args (get @synths* sname)])
          controller (partial node-control sgroup)
          player (partial node sname :target sgroup)
          [tgt-fn args] (if (= :ctl (first args))
                          [controller (rest args)]
                          [player args])

  (try
    (group-clear 0)
    (catch Exception e nil))
  ;(apply node-free (all-ids :node))
  (clear-ids :node)
  (alloc-id :node) ; ID zero is the root group
  (dosync (ref-set synths* (zipmap (keys @synths*)
