Merge pull request #288 from open-ephys/issue-207

Document how DeviceName links configuration and data IO operators

OpenEphys.Onix1/Bno055Data.cs

@@ -10,8 +10,8 @@ namespace OpenEphys.Onix1
     /// Produces a sequence of 3D orientation measurements produced by Bno055 9-axis inertial measurement unit.
     /// </summary>
     /// <remarks>
-    /// This data stream operator must be linked to an appropriate configuration, such as a <see cref="ConfigureBno055"/>,
-    /// in order to stream 3D orientation data.
+    /// This data IO operator must be linked to an appropriate configuration operator, such as a <see
+    /// cref="ConfigureBno055"/>, using a shared <c>DeviceName</c>.
     /// </remarks>
     [Description("Produces a sequence of 3D orientation measurements produced by a Bno055 9-axis inertial measurement unit.")]
     public class Bno055Data : Source<Bno055DataFrame>

OpenEphys.Onix1/BreakoutAnalogInput.cs

@@ -12,6 +12,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Produces a sequence of analog input frames from an ONIX breakout board.
     /// </summary>
+    /// <remarks>
+    /// This data IO operator must be linked to an appropriate configuration, such as a <see
+    /// cref="ConfigureBreakoutAnalogIO"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Produces a sequence of analog input frames from an ONIX breakout board.")]
     public class BreakoutAnalogInput : Source<BreakoutAnalogInputDataFrame>
     {

OpenEphys.Onix1/BreakoutAnalogOutput.cs

@@ -10,6 +10,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Sends analog output data to an ONIX breakout board.
     /// </summary>
+    /// <remarks>
+    /// This data IO operator must be linked to an appropriate configuration, such as a <see
+    /// cref="ConfigureBreakoutAnalogIO"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Sends analog output data to an ONIX breakout board.")]
     public class BreakoutAnalogOutput : Sink<Mat>
     {

OpenEphys.Onix1/BreakoutDigitalInput.cs

@@ -10,8 +10,8 @@ namespace OpenEphys.Onix1
     /// Produces a sequence of digital input data from an ONIX breakout board.
     /// </summary>
     /// <remarks>
-    /// This data stream operator must be linked to an appropriate configuration, such as a
-    /// <see cref="ConfigureBreakoutDigitalIO"/>, in order to stream data.
+    /// This data IO operator must be linked to an appropriate configuration, such as a <see
+    /// cref="ConfigureBreakoutDigitalIO"/>, using a shared <c>DeviceName</c>.
     /// </remarks>
     [Description("Produces a sequence of digital input frames from an ONIX breakout board.")]
     public class BreakoutDigitalInput : Source<BreakoutDigitalInputDataFrame>

OpenEphys.Onix1/BreakoutDigitalOutput.cs

@@ -9,6 +9,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Sends digital output data to an ONIX breakout board.
     /// </summary>
+    /// <remarks>
+    /// This data IO operator must be linked to an appropriate configuration, such as a <see
+    /// cref="ConfigureBreakoutDigitalIO"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Sends digital output data to an ONIX breakout board.")]
     public class BreakoutDigitalOutput : Sink<BreakoutDigitalPortState>
     {

OpenEphys.Onix1/ConfigureBno055.cs

@@ -5,10 +5,10 @@ namespace OpenEphys.Onix1
 {
     /// <summary>
     /// Configures a Bosch Bno055 9-axis inertial measurement unit (IMU).
-    /// </summary>C
+    /// </summary>
     /// <remarks>
-    /// This configuration operator can be linked to a <see cref="Bno055Data"/> instance to stream
-    /// orientation data from the IMU.
+    /// This configuration operator can be linked to a data IO operator, such as <see cref="Bno055Data"/>,
+    /// using a shared <c>DeviceName</c>.
     /// </remarks>
     [Description("Configures a Bosch Bno055 9-axis inertial measurement unit.")]
     [Editor("OpenEphys.Onix1.Design.Bno055Editor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]

OpenEphys.Onix1/ConfigureBreakoutAnalogIO.cs

@@ -7,6 +7,11 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures the ONIX breakout board's analog inputs and outputs.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to data IO operators, such as <see
+    /// cref="BreakoutAnalogInput"/> and <see cref="BreakoutAnalogOutput"/>, using a shared
+    /// <c>DeviceName</c>.
+    /// </remarks>
     [TypeConverter(typeof(SortedPropertyConverter))]
     [Description("Configures the ONIX breakout board's analog inputs and outputs.")]
     public class ConfigureBreakoutAnalogIO : SingleDeviceFactory

OpenEphys.Onix1/ConfigureBreakoutDigitalIO.cs

@@ -6,6 +6,11 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures the ONIX breakout board's digital inputs and outputs.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to data IO operators, such as <see
+    /// cref="BreakoutDigitalInput"/> and <see cref="BreakoutDigitalOutput"/>, using a shared
+    /// <c>DeviceName</c>.
+    /// </remarks>
     [Description("onfigures the ONIX breakout board's digital inputs and outputs.")]
     public class ConfigureBreakoutDigitalIO : SingleDeviceFactory
     {

OpenEphys.Onix1/ConfigureHarpSyncInput.cs

@@ -9,6 +9,10 @@ namespace OpenEphys.Onix1
     /// </summary>
     /// <remarks>
     /// <para>
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="HarpSyncInput"/>, using a shared <c>DeviceName</c>.
+    /// </para>
+    /// <para>
     /// Harp is a standard for asynchronous real-time data acquisition and experimental
     /// control in neuroscience. It includes a clock synchronization protocol which allows
     /// Harp devices to be connected to a shared clock line and continuously self-synchronize

OpenEphys.Onix1/ConfigureHeadstage64ElectricalStimulator.cs

@@ -7,10 +7,9 @@ namespace OpenEphys.Onix1
     /// Configures a headstage-64 onboard electrical stimulator.
     /// </summary>
     /// <remarks>
-    /// This configuration operator can be linked to a <see cref="Headstage64ElectricalStimulatorTrigger"/>
-    /// instance to deliver current controlled electrical micro-stimulation through a contact on the probe
-    /// connector on the bottom of the headstage or the corresponding contact on a compatible electrode
-    /// interface board.
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="Headstage64ElectricalStimulatorTrigger"/>, using a shared
+    /// <c>DeviceName</c>.
     /// </remarks>
     [Description("Configures a headstage-64 onboard electrical stimulator.")]
     public class ConfigureHeadstage64ElectricalStimulator : SingleDeviceFactory

OpenEphys.Onix1/ConfigureHeadstage64OpticalStimulator.cs

@@ -7,9 +7,9 @@ namespace OpenEphys.Onix1
     /// Configures a headstage-64 dual-channel optical stimulator.
     /// </summary>
     /// <remarks>
-    /// This configuration class can be linked to a <see cref="Headstage64OpticalStimulatorTrigger"/> instance
-    /// to drive current through laser diodes or LEDs connected to two contacts on the probe connector on the
-    /// bottom of the headstage or the corresponding contacts on a compatible electrode interface board.
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="Headstage64OpticalStimulatorTrigger"/>, using a shared
+    /// <c>DeviceName</c>.
     /// </remarks>
     [Description("Configures a headstage-64 dual-channel optical stimulator.")]
     public class ConfigureHeadstage64OpticalStimulator : SingleDeviceFactory

OpenEphys.Onix1/ConfigureHeartbeat.cs

@@ -8,11 +8,11 @@ namespace OpenEphys.Onix1
 {
     /// <summary>
     /// Configures a heartbeat device.
+    /// </summary>
     /// <remarks>
-    /// This configuration operator can be linked to a <see cref="HeartbeatData"/> instance to stream
-    /// heartbeats from the acquisition system.
+    /// This configuration operator can be linked to a data IO operator, such as <see cref="HeartbeatData"/>,
+    /// using a shared <c>DeviceName</c>.
     /// </remarks>
-    /// </summary>
     [Description("Configures a heartbeat device.")]
     public class ConfigureHeartbeat : SingleDeviceFactory
     {

OpenEphys.Onix1/ConfigureLoadTester.cs

@@ -7,12 +7,15 @@
 
 namespace OpenEphys.Onix1
 {
+    // TODO: Add data IO operators, update XML comment to link to them (<see cref="LoadTesterData"/>)
     /// <summary>
     /// Configures a load tester device.
     /// </summary>
     /// <remarks>
-    /// The load tester device can be configured to produce data at user-settable size and rate
-    /// to stress test various communication links and test closed-loop response latency.
+    /// This configuration operator can be linked to a data IO operator, such as LoadTesterData,
+    /// using a shared <c>DeviceName</c>. The load tester device can be configured
+    /// to produce data at user-settable size and rate to stress test various communication links and test
+    /// closed-loop response latency.
     /// </remarks>
     [Description("Configures a load testing device.")]
     public class ConfigureLoadTester : SingleDeviceFactory

OpenEphys.Onix1/ConfigureMemoryMonitor.cs

@@ -8,19 +8,24 @@ namespace OpenEphys.Onix1
     /// Configures a hardware memory monitor.
     /// </summary>
     /// <remarks>
-    /// The memory monitor produces periodic snapshots of the system's first in, first out (FIFO) data buffer.
-    /// This can be useful for:
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="MemoryMonitorData"/>, using a shared <c>DeviceName</c>.The memory
+    /// monitor produces periodic snapshots of the system's first in, first out (FIFO) data buffer. This can
+    /// be useful for:
     /// <list type="bullet">
     /// <item>
-    /// <description>Ensuring that data is being read by the host PC quickly enough to prevent real-time delays or overflows.
-    /// In the case that the PC is not keeping up with data collection, FIFO memory use will increase monotonically.</description>
+    /// <description>Ensuring that data is being read by the host PC quickly enough to prevent real-time
+    /// delays or overflows. In the case that the PC is not keeping up with data collection, FIFO memory use
+    /// will increase monotonically.</description>
     /// </item>
     /// <item>
-    /// <description>Tuning the value of <see cref="StartAcquisition.ReadSize"/> to optimize real-time performance.
-    /// For optimal real-time performance, <see cref="StartAcquisition.ReadSize"/> should be as small as possible and the FIFO should be bypassed
-    /// (memory usage should remain at 0). However, these requirements are in conflict. The memory monitor provides a way to find the minimal value of
-    /// value of <see cref="StartAcquisition.ReadSize"/> that does not result in excessive FIFO data buffering. This tradeoff will depend on the
-    /// bandwidth of data being acquired, the performance of the host PC, and downstream real-time processing.</description>
+    /// <description>Tuning the value of <see cref="StartAcquisition.ReadSize"/> to optimize real-time
+    /// performance. For optimal real-time performance, <see cref="StartAcquisition.ReadSize"/> should be as
+    /// small as possible and the FIFO should be bypassed (memory usage should remain at 0). However, these
+    /// requirements are in conflict. The memory monitor provides a way to find the minimal value of value of
+    /// <see cref="StartAcquisition.ReadSize"/> that does not result in excessive FIFO data buffering. This
+    /// tradeoff will depend on the bandwidth of data being acquired, the performance of the host PC, and
+    /// downstream real-time processing.</description>
     /// </item>
     /// </list>
     /// </remarks>

OpenEphys.Onix1/ConfigureNeuropixelsV1e.cs

@@ -9,6 +9,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures a NeuropixelsV1e device.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to a data IO operator, such as <see cref="NeuropixelsV1eData"/>,
+    /// using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Configures a NeuropixelsV1e device.")]
     [Editor("OpenEphys.Onix1.Design.NeuropixelsV1eEditor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]
     public class ConfigureNeuropixelsV1e : SingleDeviceFactory

OpenEphys.Onix1/ConfigureNeuropixelsV1eBno055.cs

@@ -6,6 +6,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures a NeuropixelsV1eBno055 device.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="NeuropixelsV1eBno055Data"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Configures a NeuropixelsV1eBno055 device.")]
     [Editor("OpenEphys.Onix1.Design.NeuropixelsV1eBno055Editor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]
     public class ConfigureNeuropixelsV1eBno055 : SingleDeviceFactory

OpenEphys.Onix1/ConfigureNeuropixelsV2e.cs

@@ -293,7 +293,7 @@ static class NeuropixelsV2e
         public const byte ProbeBSelected = 0b1001_1001;
 
         public const int FramesPerSuperFrame = 16;
-        public const int ADCsPerProbe = 24;
+        public const int AdcsPerProbe = 24;
         public const int ChannelCount = 384;
         public const int FrameWords = 36; // TRASH TRASH TRASH 0 ADC0 ADC8 ADC16 0 ADC1 ADC9 ADC17 0 ... ADC7 ADC15 ADC23 0
 

OpenEphys.Onix1/ConfigureNeuropixelsV2eBeta.cs

@@ -9,6 +9,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures a NeuropixelsV2eBeta device.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="NeuropixelsV2eData"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Description("Configures a NeuropixelsV2eBeta device.")]
     [Editor("OpenEphys.Onix1.Design.NeuropixelsV2eEditor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]
     public class ConfigureNeuropixelsV2eBeta : SingleDeviceFactory, IConfigureNeuropixelsV2

OpenEphys.Onix1/ConfigureNeuropixelsV2eBno055.cs

@@ -6,6 +6,10 @@ namespace OpenEphys.Onix1
     /// <summary>
     /// Configures a NeuropixelsV2eBno055 device.
     /// </summary>
+    /// <remarks>
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="NeuropixelsV2eBno055Data"/>, using a shared <c>DeviceName</c>.
+    /// </remarks>
     [Editor("OpenEphys.Onix1.Design.NeuropixelsV2eBno055Editor, OpenEphys.Onix1.Design", typeof(ComponentEditor))]
     [Description("Configures a NeuropixelsV2eBno055 device.")]
     public class ConfigureNeuropixelsV2eBno055 : SingleDeviceFactory

OpenEphys.Onix1/ConfigureRhd2164.cs

@@ -7,8 +7,8 @@ namespace OpenEphys.Onix1
     /// Configures an Intan Rhd2164 bioamplifier chip.
     /// </summary>
     /// <remarks>
-    /// This configuration operator can be linked to a <see cref="Rhd2164Data"/> instance to stream
-    /// electrophysiology data from the chip.
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="Rhd2164Data"/>, using a shared <c>DeviceName</c>.
     /// </remarks>
     [Description("Configures a Rhd2164 device.")]
     public class ConfigureRhd2164 : SingleDeviceFactory

OpenEphys.Onix1/ConfigureTS4231V1.cs

@@ -8,8 +8,10 @@ namespace OpenEphys.Onix1
     /// a pair of SteamVR V1 base stations.
     /// </summary>
     /// <remarks>
-    /// This configuration operator can be linked to a <see cref="TS4231V1PositionData"/> instance to stream 3D position data from
-    /// light-house receivers when SteamVR V1 base stations have been installed above the arena.
+    /// This configuration operator can be linked to a data IO operator, such as <see
+    /// cref="TS4231V1PositionData"/>, using a shared <c>DeviceName</c> to stream 3D
+    /// position data from light-house receivers when SteamVR V1 base stations have been installed above the
+    /// arena.
     /// </remarks>
     [Description("Configures a TS4231 receiver array.")]
     public class ConfigureTS4231V1 : SingleDeviceFactory

OpenEphys.Onix1/DeviceFactory.cs

@@ -23,14 +23,13 @@ public abstract class DeviceFactory : Sink<ContextTask>
     }
 
     /// <summary>
-    /// Provides an abstract base class for configuration operators responsible for
-    /// registering a single device within the internal device manager.
+    /// Abstract base for configuration operators responsible for registering a single device within the
+    /// internal device manager.
     /// </summary>
     /// <remarks>
-    /// ONI devices usually require a specific sequence of configuration and parameterization
-    /// steps before they can be interacted with. The <see cref="SingleDeviceFactory"/>
-    /// provides a modular abstraction allowing flexible assembly and sequencing of
-    /// of all device-specific configuration code.
+    /// ONI devices usually require a specific sequence of configuration and parameterization steps before
+    /// they can be interacted with. The <see cref="SingleDeviceFactory"/> provides a modular abstraction
+    /// allowing flexible assembly and sequencing of of all device-specific configuration code.
     /// </remarks>
     public abstract class SingleDeviceFactory : DeviceFactory, IDeviceConfiguration
     {
@@ -47,9 +46,11 @@ internal SingleDeviceFactory(Type deviceType)
         /// </summary>
         /// <remarks>
         /// The device name provides a unique, human-readable identifier that is used to link software
-        /// elements for configuration, control, and data streaming to hardware. This is often a one-to-one
-        /// representation of a single <see cref="oni.Device"/>, but can also represent abstract ONI device
-        /// aggregates or virtual devices.
+        /// elements for configuration, control, and data streaming to hardware. For instance, it can be used
+        /// to link configuration operators to data IO operators within a workflow. This value is
+        /// usually not set manually, but is assigned in a <see cref="MultiDeviceFactory"/> to correspond to a
+        /// fixed address with a piece of hardware such as a headstage. This address is used for software
+        /// communication.
         /// </remarks>
         [Description(DeviceNameDescription)]
         [Category(ConfigurationCategory)]
@@ -59,8 +60,11 @@ internal SingleDeviceFactory(Type deviceType)
         /// Gets or sets the device address.
         /// </summary>
         /// <remarks>
-        /// This address provides a fully-qualified location of a device within the device table. This is often a one-to-one
-        /// representation of a <see cref="oni.Device.Address"/>, but can also represent abstract device addresses.
+        /// This is a fully-qualified numerical hardware address of a device within the device table produced
+        /// by an <see href="https://open-ephys.github.io/ONI/">Open Neuro Interface (ONI)</see> compliant
+        /// acquisition system. This value is usually not set manually, but is assigned in a <see
+        /// cref="MultiDeviceFactory"/> to correspond to a fixed address with a piece of hardware such as a
+        /// headstage. This address is used for hardware communication.
         /// </remarks>
         [Description(DeviceAddressDescription)]
         [Category(ConfigurationCategory)]
@@ -70,8 +74,9 @@ internal SingleDeviceFactory(Type deviceType)
         /// Gets or sets the device identity.
         /// </summary>
         /// <remarks>
-        /// This type provides a device identity to each device within the device table. This is often a one-to-one
-        /// representation of a a <see cref="oni.Device.ID"/>, but can also represent abstract device identities.
+        /// This type provides a device identity to each device within the device table produced by an <see
+        /// href="https://open-ephys.github.io/ONI/">Open Neuro Interface (ONI)</see> compliant acquisition
+        /// system.
         /// </remarks>
         [Browsable(false)]
         public Type DeviceType { get; }

OpenEphys.Onix1/HarpSyncInputData.cs

@@ -7,7 +7,8 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Produces a sequence of Harp clock synchronization signals sent to the Harp input in the ONIX breakout board.
+    /// Produces a sequence of Harp clock synchronization signals sent to the Harp input in the ONIX breakout
+    /// board.
     /// </summary>
     /// <inheritdoc cref = "ConfigureHarpSyncInput"/>
     [Description("Produces a sequence of Harp clock synchronization signals sent to the Harp input in the ONIX breakout board.")]