From 7f0d95d34b412322f0af17dc55db9dab4fd6d0cb Mon Sep 17 00:00:00 2001
From: David Runge <dave@sleepmap.de>
Date: Wed, 30 Dec 2020 01:16:39 +0100
Subject: Add HelpSource for ZZZ, ZZZDevice and ZZZError

Add schelp files for ZZZ, ZZZDevice and ZZZError, explaining (mostly
all) class and instance methods and giving code examples.
---
 HelpSource/Classes/ZZZ.schelp       | 179 ++++++++++++++++++++++
 HelpSource/Classes/ZZZDevice.schelp | 289 ++++++++++++++++++++++++++++++++++++
 HelpSource/Classes/ZZZError.schelp  |  22 +++
 3 files changed, 490 insertions(+)
 create mode 100644 HelpSource/Classes/ZZZ.schelp
 create mode 100644 HelpSource/Classes/ZZZDevice.schelp
 create mode 100644 HelpSource/Classes/ZZZError.schelp

diff --git a/HelpSource/Classes/ZZZ.schelp b/HelpSource/Classes/ZZZ.schelp
new file mode 100644
index 0000000..f62a95c
--- /dev/null
+++ b/HelpSource/Classes/ZZZ.schelp
@@ -0,0 +1,179 @@
+TITLE:: ZZZ
+summary:: Abstract superclass of all module specific Expert Sleepers classes
+categories:: External Control>Eurorack
+related:: Classes/ZZZDevice
+
+DESCRIPTION:: Users will normally not directly create instances of ZZZ, but
+only use it through its subclasses. It provides basic conversion methods, that
+can be used to drive DC coupled hardware of the Eurorack standard.
+Additionally it provides link::Classes/SynthDef##SynthDefs::, which will be
+added during instantiation, that can be used for clock and gate signals.
+
+CLASSMETHODS::
+
+subsection:: Initialization
+
+METHOD:: new
+Initialize a new instance.
+
+note::Do not call this method directly but instead derive a class from this one
+and use this method in the child's classes initialization method (see
+link::Classes/ZZZDevice:: for an example).::
+
+ARGUMENT:: channels
+An link::Classes/Array:: of link::Classes/Integer##Integers:: representing
+output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on a
+link::Classes/Server::.
+
+ARGUMENT:: server
+An instance of link::Classes/Server::.
+
+returns:: An instance of link::Classes/ZZZ::.
+
+METHOD:: initClass
+Uses link::Classes/StartUp#*add:: to add link::Classes/SynthDef##SynthDefs:: 
+used by child classes.
+
+list::
+## code::\ZZZGate::: A gate link::Classes/SynthDef:: utilizing link::Classes/DC::.
+## code::\ZZZClock::: A clock link::Classes/SynthDef:: (24 beats per quarter
+note) utilizing link::Classes/LFPulse::.
+## code::\ZZZClockKorg::: A clock link::Classes/SynthDef:: (48 beats per quarter
+note) utilizing link::Classes/LFPulse::.
+::
+
+subsection::Conversion
+
+METHOD:: ampmidi
+Calculates midi note for supplied amplitude.
+
+ARGUMENT:: amplitude
+Amplitude in the range from 0.0 to 1.0.
+
+returns:: MIDI note for corresponding amplitude, nil if amplitude is not within
+the allowed octave range.
+
+METHOD:: noteCpsRangeMax
+Cps for MIDI note C10.
+
+returns:: Returns cps for MIDI note C10.
+
+METHOD:: cvMaxADSR
+Maximum voltage for ADSR on Eurorack modules.
+
+returns:: Returns maximum voltage for ADSR.
+
+METHOD:: noteCpsRangeMin
+Cps for MIDI note C-2.
+
+returns:: Returns cps for MIDI note C-2.
+
+METHOD:: midiamp
+Calculates amplitude for supplied MIDI note.
+
+ARGUMENT:: midi
+MIDI note.
+
+returns:: Amplitude for corresponding midi note, nil if < 0 or > 127
+
+METHOD:: cvMinADSR
+Minimum voltage for ADSR on Eurorack modules.
+
+returns:: Returns minimum voltage for ADSR.
+
+METHOD:: cvMaxTriggerGateClock
+Maximum trigger/gate/clock control voltage for Eurorack modules.
+
+returns:: Returns maximum maximum trigger/gate/clock control voltage for Eurorack modules.
+
+METHOD:: cpsvoltage
+Calculates voltage for supplied cycles per second.
+
+ARGUMENT:: cps
+Cycles per seconds
+
+returns:: Returns voltage for corresponding cycles per second.
+
+METHOD:: noteVoltageRangeMin
+Maximum voltage for a note on Eurorack modules.
+
+returns:: Returns maximum voltage for notes.
+
+METHOD:: amplitudevoltage
+(describe method here)
+
+ARGUMENT:: amplitude
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMaxLFO
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: noteVoltageRangeMax
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: ampcps
+(describe method here)
+
+ARGUMENT:: amplitude
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMinTriggerGateClock
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: voltageamplitude
+(describe method here)
+
+ARGUMENT:: voltage
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cpsamp
+(describe method here)
+
+ARGUMENT:: cps
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: cvMinLFO
+(describe method here)
+
+returns:: (describe returnvalue here)
+
+METHOD:: voltagecps
+(describe method here)
+
+ARGUMENT:: voltage
+(describe argument here)
+
+returns:: (describe returnvalue here)
+
+
+INSTANCEMETHODS::
+
+METHOD:: channels
+Returns an link::Classes/Array:: of link::Classes/Integer##Integers:: 
+representing output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on a
+link::Classes/Server:: that was used in link::#*new:: to initialize an instance
+of this class (or any of its subclasses).
+
+returns:: An link::Classes/Array:: of link::Classes/Integer##Integers::.
+
+METHOD:: server
+Returns a link::Classes/Server:: instance that was used in link::#*new:: to
+initialize an instance of this class (or any of its subclasses).
+
+returns:: A link::Classes/Server:: instance.
diff --git a/HelpSource/Classes/ZZZDevice.schelp b/HelpSource/Classes/ZZZDevice.schelp
new file mode 100644
index 0000000..b23b2c3
--- /dev/null
+++ b/HelpSource/Classes/ZZZDevice.schelp
@@ -0,0 +1,289 @@
+TITLE:: ZZZDevice
+summary:: Interface Expert Sleepers devices
+categories:: External Control>Eurorack
+related:: Classes/ZZZ, Reference/ZZZ
+
+DESCRIPTION::
+This class provides an interface to Expert Sleepers' Eurorack modules.
+It offers convenience methods to create clocks and gates on the device's
+outputs, based on (shared) link::Classes/TempoBusClock##TempoBusClocks::.
+
+note:: ZZZDevice assumes that the (ADAT) channels used to interface with the Eurorack module are set to 0.0dB at +4dBu.::
+
+CLASSMETHODS::
+
+METHOD:: new
+Creates an instance of ZZZDevice on a link::Classes/Server:: using an
+link::Classes/Array:: of output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::).
+Throws link::Classes/ZZZError:: if the parameters ar not set or invalid.
+
+ARGUMENT:: channels
+An link::Classes/Array:: of link::Classes/Integer##Integers::, that represent
+output bus channels indeces (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) on the
+link::Classes/Server:: instance.
+
+ARGUMENT:: server
+The link::Classes/Server:: instance to use.
+
+returns:: An instance of ZZZDevice interfacing the given hardware device.
+
+METHOD:: playTypes
+Return the understood playTypes that can be used. A code::playType:: relates to
+how scheduling takes place on a given link::Classes/TempoBusClock:: when adding
+or changing clocks on an output:
+
+list::
+## code::\beat::: When this code::playType:: is used the clock is added/ changed/ removed on the next beat.
+## code::\bar::: When this code::playType:: is used the clock is added/ changed/ removed on the next bar.
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols:: 
+representing the understood code::playTypes::.
+
+METHOD:: clockTypes
+Return the understood types of clocks that can be used:
+
+list::
+## code::\zeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (24 beats per qarter note)
+## code::\minusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (24 beats per qarter note)
+## code::\korgZeroFive::: A clock signal ranging from code::0.0:: to code::5.0:: (48 beats per quarter note)
+## code::\korgMinusFiveFive::: A clock signal ranging from code::-5.0:: to code::5.0:: (48 beats per quarter note)
+::
+
+returns:: An link::Classes/Array:: of link::Classes/Symbol##Symbols:: 
+representing the understood code::clockTypes::.
+
+
+INSTANCEMETHODS::
+
+subsection::Initialization
+
+METHOD:: init
+Initializes the link::Classes/Dictionary##Dictionaries:: required for
+link::#-clocks::, link::#-gates::, link::#-gateBusses::, link::#-outs::,
+link::#-tempos:: and link::#-tempoBusses::, as well as populates the
+link::#-outs:: link::Classes/Dictionary:: and initializes link::#-deviceGroup:: 
+when the link::Classes/Server:: is booted.
+
+note::This method is called when creating a new instance of ZZZDevice using link::#*new::.::
+
+subsection::Adding and Removing
+
+METHOD:: addTempo
+Adds a link::Classes/TempoBusClock:: to the link::#-tempos:: link::Classes/Dictionary::. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the slot to use for the link::Classes/TempoBusClock::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+METHOD:: removeTempo
+Removes a link::Classes/TempoBusClock:: from the link::#-tempos:: link::Classes/Dictionary:: and any clock relying on it.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the tempo and clock link::Classes/Synth##Synth(s)::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addClock
+Adds a clock link::Classes/Synth:: on a hardware output. Throws
+link::Classes/ZZZError:: on invalid input.
+
+note::Requires a tempo to be setup beforehand (see link::#-addTempo::).::
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the tempo slot to use for the clock (see link::#-addTempo:: on how to add a tempo).
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: replace
+A link::Classes/Boolean:: indicating whether to replace clock currently playing at code::output::.
+
+METHOD:: removeClock
+Removes a clock link::Classes/Synth:: playing on a hardware output.
+Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule removal of the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+METHOD:: addGate
+Adds a gate link::Classes/Synth:: on a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+The gate's multiplication value can be controlled using the respective link::Classes/Bus:: exposed in link::#-gateBusses::.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+ARGUMENT:: input
+A link::Classes/Float:: (code::>=0.0, <=1.0::) setting the initial multiplication value.
+
+METHOD:: removeGate
+Removes a gate link::Classes/Synth:: from a hardware output. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+subsection::Setting Data
+
+METHOD:: setClockTempo
+Sets the link::Classes/TempoBusClock:: used for a given clock on an code::output:: of an Expert Sleepers device. Throws link::Classes/ZZZError:: on invalid input.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on ahardware device.
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: playType
+A link::Classes/Symbol:: describing the code::playType:: to use (see link::#*playTypes:: for the valid types and explanation).
+
+ARGUMENT:: quant
+An link::Classes/Integer:: setting the quant (the beat) on which to schedule playing the clock link::Classes/Synth::.
+Only regarded if code::playType:: is set to code::\beat::.
+
+ARGUMENT:: type
+A link::Classes/Symbol:: describing the clock type to use (see link::#*clockTypes:: for the valid types and explanation).
+
+METHOD:: setTempo
+Sets the tempo of a link::Classes/TempoBusClock:: (see link::#-addTempo:: on how to add a tempo).
+
+note::It may prove more pragmatic to write to the tempo's respective link::Classes/Bus:: in link::#-tempoBusses::.::
+
+ARGUMENT:: slot
+An link::Classes/Integer:: (code::>=1::) identifying the link::Classes/TempoBusClock:: in the link::#-tempos:: link::Classes/Dictionary::.
+
+ARGUMENT:: tempo
+A link::Classes/Float:: (code::>=0.0::) setting the tempo.
+
+subsection::Accessing Data
+
+METHOD:: clocks
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective clock link::Classes/Synth##Synths:: (see link::#-addClock:: on how to add a clock).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: deviceGroup
+Returns the link::Classes/Group:: instance to which all link::Classes/Synth##Synths:: are added.
+This variable is setup during link::#-init::.
+
+returns:: A link::Classes/Group::.
+
+METHOD:: gateBusses
+Returns a link::Classes/Dictionary:: of hardware outputs and their respective
+link::Classes/Bus##Busses:: connected to the gate
+link::Classes/Synth##Synths:: (see link::#-addGate:: on how to setup a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: gates
+Returns a link::Classes/Dictionary:: of hardware output numbers and their
+respective gate link::Classes/Synth##Synths:: (see link::#-addGate:: on how to
+add a gate).
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Synth:: associations.
+
+METHOD:: outs
+Returns a link::Classes/Dictionary:: representing the mapping between the outputs
+on the hardware (the numbering starts at code::1::) and the
+link::Classes/Server::'s output bus channels (within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) connected to the hardware.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: associations.
+
+METHOD:: outputOnHardware
+Returns the output bus channel (an link::Classes/Integer:: within the range of
+link::Classes/ServerOptions#-numOutputBusChannels::) mapped to a given hardware
+output number.
+Throws link::Classes/ZZZError:: if the output parameter is invalid.
+
+ARGUMENT:: output
+An link::Classes/Integer:: (code::>=1::) identifying the code::output:: on a hardware device.
+
+returns:: An link::Classes/Integer:: representing an output bus channel.
+
+METHOD:: tempoBusses
+Returns a link::Classes/Dictionary:: of slots (starting from code::1::) and
+their respective link::Classes/Bus##Busses::, which are connected to
+link::Classes/TempoBusClock##TempoBusClocks:: and clock link::Classes/Synth##Synths::.
+
+returns:: A link::Classes/Dictionary:: of link::Classes/Integer:: and link::Classes/Bus:: associations.
+
+METHOD:: tempos
+Returns a link::Classes/Dictionary:: of the currently available tempos (see
+link::#-addTempo:: on how to setup a tempo).
+
+returns:: A link::Classes/Dictionary:: of slots (link::Classes/Integer::) and link::Classes/TempoBusClock:: associations.
+
+subsection::Posting Information
+
+METHOD:: postAll
+Convenience wrapper around link::#-postClocks::, link::#-postGates::, link::#-postOuts:: and link::#-postTempos::.
+
+METHOD:: postClocks
+Posts information about the currently running clocks.
+
+METHOD:: postGates
+Posts information about the currently running gate link::Classes/Synth##Synth(s)::.
+
+METHOD:: postOuts
+Posts information about the mapping of hardware outputs to link::Classes/Server:: output bus channels.
+
+METHOD:: postTempos
+Posts information about the currently running link::Classes/TempoBusClock##TempoBusClocks::.
+
+EXAMPLES::
+
+code::
+// first Server output bus channel of ADAT connection to Expert Sleepers hardware device
+// this might be different depending on hardware or sclang startup configuration
+~firstChannel = 12;
+
+// initialize connection
+s.waitForBoot(
+  ~zzzdevice = ZZZDevice.new(server: s, channels: Array.series(8, start: ~firstChannel, step: 1));
+);
+
+// add a tempo
+~zzzdevice.addTempo(slot: 1, tempo: 120/60);
+
+// add a clock on the first hardware output using the above tempo
+~zzzdevice.addClock(output: 1, slot: 1);
+
+// add a gate on the second hardware output
+~zzzdevice.addGate(output: 6);
+
+// set the tempo
+~zzzdevice.setTempo(slot: 1, tempo: 180/60);
+
+// remove everything
+(
+  ~zzzdevice.removeTempo(slot: 1);
+  ~zzzdevice.removeGate(output: 6);
+)
+::
diff --git a/HelpSource/Classes/ZZZError.schelp b/HelpSource/Classes/ZZZError.schelp
new file mode 100644
index 0000000..49bf0d0
--- /dev/null
+++ b/HelpSource/Classes/ZZZError.schelp
@@ -0,0 +1,22 @@
+TITLE:: ZZZError
+summary:: Errors for ZZZ
+categories:: External Control>Eurorack
+related:: Classes/ZZZ, Classes/ZZZDevice, Classes/Error
+
+DESCRIPTION::
+An link::Classes/Error:: class for link::Classes/ZZZ:: and its subclasses.
+
+
+CLASSMETHODS::
+
+
+INSTANCEMETHODS::
+
+
+EXAMPLES::
+
+code::
+// throw a ZZZError
+ZZZError("Something went wrong!").throw;
+::
+
-- 
cgit v1.2.3-54-g00ecf