docstring cleanup

src/overtone/libs/event.clj

@@ -8,50 +8,55 @@
 (defonce handler-pool (handlers/mk-handler-pool "Overtone Event Handlers"))
 
 (defn on-event
- "Asynchronously runs handler whenever events of event-type are fired. This
- asynchronous behaviour can be overridden if required - see sync-event for
- more information. Events may be triggered with the fns event and sync-event.
+ "Asynchronously runs handler whenever events of event-type are
+ fired. This asynchronous behaviour can be overridden if required -
+ see sync-event for more information. Events may be triggered with
+ the fns event and sync-event.
 
- Takes an event-type (name of the event), a handler fn and a key (to refer
- back to this handler in the future). The handler can optionally accept a
- single event argument, which is a map containing the :event-type property
- and any other properties specified when it was fired.
+ Takes an event-type (name of the event), a handler fn and a key (to
+ refer back to this handler in the future). The handler can
+ optionally accept a single event argument, which is a map containing
+ the :event-type property and any other properties specified when it
+ was fired.
 
  (on-event \"/tr\" handler ::status-check )
  (on-event :midi-note-down (fn [event]
  (funky-bass (:note event)))
  ::midi-note-down-hdlr)
 
- Handlers can return :done to be removed from the handler list after execution."
+ Handlers can return :overtone/remove-handler to be removed from the
+ handler list after execution."
  [event-type handler key]
  (log/debug "Registering async event handler:: " event-type key)
  (handlers/add-handler handler-pool event-type key handler ))
 
 (defn on-sync-event
- "Synchronously runs handler whenever events of type event-type are fired on
- the event handling thread i.e. causes the event handling thread to block until
- all sync events have been handled. Events may be triggered with the fns event
- and sync-event.
+ "Synchronously runs handler whenever events of type event-type are
+ fired on the event handling thread i.e. causes the event handling
+ thread to block until all sync events have been handled. Events may
+ be triggered with the fns event and sync-event.
 
- Takes an event-type (name of the event), a handler fn and a key (to refer
- back to this handler in the future). The handler can optionally accept a
- single event argument, which is a map containing the :event-type property
- and any other properties specified when it was fired.
+ Takes an event-type (name of the event), a handler fn and a key (to
+ refer back to this handler in the future). The handler can
+ optionally accept a single event argument, which is a map containing
+ the :event-type property and any other properties specified when it
+ was fired.
 
  (on-event \"/tr\" handler ::status-check )
  (on-event :midi-note-down (fn [event]
  (funky-bass (:note event)))
  ::midi-note-down-hdlr)
 
- Handlers can return :done to be removed from the handler list after execution."
+ Handlers can return :overtone/remove-handler to be removed from the
+ handler list after execution."
  [event-type handler key]
  (log/debug "Registering sync event handler:: " event-type key)
  (handlers/add-sync-handler handler-pool event-type key handler))
 
 (defn remove-handler
- "Remove an event handler previously registered to handle events of event-type.
- Removes both sync and async handlers with a given key for a particular event
- type.
+ "Remove an event handler previously registered to handle events of
+ event-type. Removes both sync and async handlers with a given key
+ for a particular event type.
 
  (defn my-foo-handler [event] (do-stuff (:val event))
 
@@ -64,15 +69,17 @@
  (handlers/remove-handler handler-pool event-type key))
 
 (defn remove-all-handlers
- "Remove all handlers (both sync and async) for events of type event-type."
+ "Remove all handlers (both sync and async) for events of type
+ event-type."
  [event-type]
  (handlers/remove-event-handlers handler-pool event-type))
 
 (defn event
- "Fire an event of type event-type with any number of additional properties.
+ "Fire an event of type event-type with any number of additional
+ properties.
 
- NOTE: an event requires key/value pairs, and everything gets wrapped into an
- event map. It will not work if you just pass values.
+ NOTE: an event requires key/value pairs, and everything gets wrapped
+ into an event map. It will not work if you just pass values.
 
  (event ::my-event)
  (event ::filter-sweep-done :instrument :phat-bass)"

src/overtone/sc/machinery/server/comms.clj

@@ -19,8 +19,8 @@
  ::osc-receiver)
 
 (defn- massage-numerical-args
- "Massage numerical args to the form SC would like them. Currently this just
- casts all Longs to Integers and Doubles to Floats."
+ "Massage numerical args to the form SC would like them. Currently
+ this just casts all Longs to Integers and Doubles to Floats."
  [args]
  (map (fn [arg]
  (cond (instance? Long arg)
@@ -34,10 +34,10 @@
  args))
 
 (defn server-snd
- "Sends an OSC message to the server. If the message path is a known scsynth
- path, then the types of the arguments will be checked according to what
- scsynth is expecting. Automatically converts any args which are longs to ints
- and doubles to floats.
+ "Sends an OSC message to the server. If the message path is a known
+ scsynth path, then the types of the arguments will be checked
+ according to what scsynth is expecting. Automatically converts any
+ args which are longs to ints and doubles to floats.
 
  (server-snd \"/foo\" 1 2.0 \"eggs\")"
  [path & args]
@@ -48,8 +48,9 @@
  (apply validated-snd @server-osc-peer* path args)))
 
 (defn on-server-sync
- "Registers the handler to be executed when all the osc messages generated
- by executing the action-fn have completed. Returns result of action-fn."
+ "Registers the handler to be executed when all the osc messages
+ generated by executing the action-fn have completed. Returns result
+ of action-fn."
  [action-fn handler-fn]
  (let [id (next-id ::server-sync-id)
  key (uuid)]
@@ -65,18 +66,19 @@
  res)))
 
 (defn server-sync
- "Send a sync message to the server with the specified id. Server will reply
- with a synced message when all incoming messages up to the sync message have
- been handled. See with-server-sync and on-server-sync for more typical
- usage."
+ "Send a sync message to the server with the specified id. Server
+ will reply with a synced message when all incoming messages up to
+ the sync message have been handled. See with-server-sync and
+ on-server-sync for more typical usage."
  [id]
  (server-snd "/sync" id))
 
 (defn with-server-self-sync
- "Blocks the current thread until the action-fn explicitly sends a server sync.
- The action-fn is assumed to have one argument which will be the unique sync id.
- This is useful when the action-fn is itself asynchronous yet you wish to
- synchronise with its completion. The action-fn can sync using the fn server-sync.
+ "Blocks the current thread until the action-fn explicitly sends a
+ server sync. The action-fn is assumed to have one argument which
+ will be the unique sync id. This is useful when the action-fn is
+ itself asynchronous yet you wish to synchronise with its
+ completion. The action-fn can sync using the fn server-sync.
  Returns the result of action-fn."
  [action-fn]
  (let [id (next-id ::server-sync-id)
@@ -93,8 +95,8 @@
  res)))
 
 (defn with-server-sync
- "Blocks current thread until all osc messages in action-fn have completed.
- Returns result of action-fn."
+ "Blocks current thread until all osc messages in action-fn have
+ completed. Returns result of action-fn."
  [action-fn]
  (let [id (next-id ::server-sync-id)
  prom (promise)
@@ -111,14 +113,15 @@
  res)))
 
 (defn server-recv
- "Register your intent to wait for a message associated with given path to be
- received from the server. Returns a promise that will contain the message once
- it has been received. Does not block current thread (this only happens once
- you try and look inside the promise and the reply has not yet been received).
+ "Register your intent to wait for a message associated with given
+ path to be received from the server. Returns a promise that will
+ contain the message once it has been received. Does not block
+ current thread (this only happens once you try and look inside the
+ promise and the reply has not yet been received).
 
- If an optional matcher-fn is specified, will only deliver the promise when
- the matcher-fn returns true. The matcher-fn should accept one arg which is
- the incoming event info."
+ If an optional matcher-fn is specified, will only deliver the
+ promise when the matcher-fn returns true. The matcher-fn should
+ accept one arg which is the incoming event info."
  ([path] (server-recv path nil))
  ([path matcher-fn]
  (let [p (promise)