Merge pull request #289 from open-ephys/issue-203

Add unique documentation to Generate() overrides

Author: jonnew

OpenEphys.Onix1/BreakoutAnalogOutput.cs

@@ -29,20 +29,29 @@ public class BreakoutAnalogOutput : Sink<Mat>
         /// Gets or sets the data type used to represent analog samples.
         /// </summary>
         /// <remarks>
-        /// If <see cref="BreakoutAnalogIODataType.S16"/> is selected, each DAC value is represented by a signed, twos-complement encoded
-        /// 16-bit integer. In this case, the output voltage always corresponds to <see cref="BreakoutAnalogIOVoltageRange.TenVolts"/>.
-        /// When <see cref="BreakoutAnalogIODataType.Volts"/> is selected, 32-bit floating point voltages between -10 and 10 volts are sent
-        /// directly to the DACs.
+        /// If <see cref="BreakoutAnalogIODataType.S16"/> is selected, each DAC value is represented by a
+        /// signed, twos-complement encoded 16-bit integer. In this case, the output voltage always
+        /// corresponds to <see cref="BreakoutAnalogIOVoltageRange.TenVolts"/>. When <see
+        /// cref="BreakoutAnalogIODataType.Volts"/> is selected, 32-bit floating point voltages between -10
+        /// and 10 volts are sent directly to the DACs.
         /// </remarks>
         [Description("The data type used to represent analog samples.")]
         [Category(DeviceFactory.ConfigurationCategory)]
         public BreakoutAnalogIODataType DataType { get; set; } = BreakoutAnalogIODataType.S16;
 
         /// <summary>
-        /// Send samples to analog outputs.
+        /// Send an matrix of samples to all enabled analog outputs.
         /// </summary>
-        /// <param name="source"> A sequence of 12xN sample matrices containing the analog data to write to channels 0 to 11.</param>
-        /// <returns> A sequence of 12xN sample matrices containing the analog data that were written to channels 0 to 11.</returns>
+        /// <remarks>
+        /// If a matrix contains multiple samples, they will be written to hardware as quickly as
+        /// communication allows. The data within each input matrix must have <see cref="Depth.S16"/> when
+        /// <c>DataType</c> is set to <see cref="BreakoutAnalogIODataType.S16"/> or <see cref="Depth.F32"/>
+        /// when <c>DataType</c> is set to <see cref="BreakoutAnalogIODataType.Volts"/>.
+        /// </remarks>
+        /// <param name="source"> A sequence of 12xN sample matrices containing the analog data to write to
+        /// channels 0 to 11.</param>
+        /// <returns> A sequence of 12xN sample matrices containing the analog data that were written to
+        /// channels 0 to 11.</returns>
         public override unsafe IObservable<Mat> Process(IObservable<Mat> source)
         {
             var dataType = DataType;
@@ -103,10 +112,17 @@ public override unsafe IObservable<Mat> Process(IObservable<Mat> source)
         }
 
         /// <summary>
-        /// Send samples to analog outputs.
+        /// Send an 12-element array of values to update all enabled analog outputs.
         /// </summary>
-        /// <param name="source"> A sequence of 12x1 element arrays each containing the analog data to write to channels 0 to 11.</param>
-        /// <returns> A sequence of 12x1 element arrays each containing the analog data to write to channels 0 to 11.</returns>
+        /// <remarks>
+        /// This overload should be used when <c>DataType</c> is set to <see
+        /// cref="BreakoutAnalogIODataType.S16"/> and values should be within -32,768 to 32,767, which
+        /// correspond to -10.0 to 10.0 volts.
+        /// </remarks>
+        /// <param name="source"> A sequence of 12x1 element arrays each containing the analog data to write
+        /// to channels 0 to 11.</param>
+        /// <returns> A sequence of 12x1 element arrays each containing the analog data to write to channels 0
+        /// to 11.</returns>
         public IObservable<short[]> Process(IObservable<short[]> source)
         {
             if (DataType != BreakoutAnalogIODataType.S16)
@@ -130,10 +146,16 @@ public IObservable<short[]> Process(IObservable<short[]> source)
         }
 
         /// <summary>
-        /// Send samples to analog outputs.
+        /// Send an 12-element array of values to update all enabled analog outputs.
         /// </summary>
-        /// <param name="source"> A sequence of 12x1 element arrays each containing the analog data to write to channels 0 to 11.</param>
-        /// <returns> A sequence of 12x1 element arrays each containing the analog data to write to channels 0 to 11.</returns>
+        /// <remarks>
+        /// This overload should be used when <c>DataType</c> is set to <see
+        /// cref="BreakoutAnalogIODataType.Volts"/> and values should be within -10.0 to 10.0 volts.
+        /// </remarks>
+        /// <param name="source"> A sequence of 12x1 element arrays each containing the analog data to write
+        /// to channels 0 to 11.</param>
+        /// <returns> A sequence of 12x1 element arrays each containing the analog data to write to channels 0
+        /// to 11.</returns>
         public IObservable<float[]> Process(IObservable<float[]> source)
         {
             if (DataType != BreakoutAnalogIODataType.Volts)

OpenEphys.Onix1/ConfigureBreakoutDigitalIO.cs

@@ -11,7 +11,7 @@ namespace OpenEphys.Onix1
     /// cref="BreakoutDigitalInput"/> and <see cref="BreakoutDigitalOutput"/>, using a shared
     /// <c>DeviceName</c>.
     /// </remarks>
-    [Description("onfigures the ONIX breakout board's digital inputs and outputs.")]
+    [Description("Configures the ONIX breakout board's digital inputs and outputs.")]
     public class ConfigureBreakoutDigitalIO : SingleDeviceFactory
     {
         /// <summary>
@@ -27,7 +27,8 @@ public ConfigureBreakoutDigitalIO()
         /// Gets or sets the device enable state.
         /// </summary>
         /// <remarks>
-        /// If set to true, <see cref="BreakoutDigitalInput"/> will produce data. If set to false, <see cref="BreakoutDigitalInput"/> will not produce data.
+        /// If set to true, <see cref="BreakoutDigitalInput"/> will produce data. If set to false, <see
+        /// cref="BreakoutDigitalInput"/> will not produce data.
         /// </remarks>
         [Category(ConfigurationCategory)]
         [Description("Specifies whether the digital IO device is enabled.")]
@@ -37,12 +38,14 @@ public ConfigureBreakoutDigitalIO()
         /// Configures the digital input and output device in the ONIX breakout board.
         /// </summary>
         /// <remarks>
-        /// This will schedule digital IO hardware configuration actions that can be applied by a
-        /// <see cref="StartAcquisition"/> object prior to data collection.
+        /// This will schedule digital IO hardware configuration actions that can be applied by a <see
+        /// cref="StartAcquisition"/> object prior to data collection.
         /// </remarks>
-        /// <param name="source">A sequence of <see cref="ContextTask"/> instances that hold configuration actions.</param>
+        /// <param name="source">A sequence of <see cref="ContextTask"/> instances that hold configuration
+        /// actions.</param>
         /// <returns>
-        /// The original sequence modified by adding additional configuration actions required to configure a digital IO device.
+        /// The original sequence modified by adding additional configuration actions required to configure a
+        /// digital IO device.
         /// </returns>
         public override IObservable<ContextTask> Process(IObservable<ContextTask> source)
         {

OpenEphys.Onix1/NeuropixelsV1eBno055Data.cs

@@ -23,13 +23,14 @@ public class NeuropixelsV1eBno055Data : Source<Bno055DataFrame>
         public string DeviceName { get; set; }
 
         /// <summary>
-        /// Generates a sequence of <see cref="Bno055DataFrame"/> objects at approximately 100 Hz.
+        /// Generates a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> at approximately 100
+        /// Hz.
         /// </summary>
-        /// <returns>A sequence of <see cref="Bno055DataFrame"/> objects.</returns>
         /// <remarks>
-        /// This will generate a sequence of <see cref="Bno055DataFrame"/> objects at approximately 100 Hz. This rate
-        /// may be limited by the I2C bus.
+        /// This will generate a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> at approximately 100 Hz.
+        /// This rate may be limited by the hardware.
         /// </remarks>
+        /// <returns>A sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see>.</returns>
         public override IObservable<Bno055DataFrame> Generate()
         {
             // Max of 100 Hz, but limited by I2C bus
@@ -38,8 +39,15 @@ public override IObservable<Bno055DataFrame> Generate()
         }
 
         /// <summary>
-        /// Generates a sequence of <see cref="Bno055DataFrame"/> objects.
+        /// Generates a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> that is driven by an
+        /// input sequence.
         /// </summary>
+        /// <remarks>
+        /// This will attempt to produce a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> that is updated whenever
+        /// an item in the <paramref name="source"/> sequence is received. This rate is be limited by the
+        /// hardware and has a maximum meaningful rate of 100 Hz.
+        /// </remarks>
+        /// <param name="source">A sequence to drive sampling.</param>
         /// <returns>A sequence of <see cref="Bno055DataFrame"/> objects.</returns>
         public unsafe IObservable<Bno055DataFrame> Generate<TSource>(IObservable<TSource> source)
         {

OpenEphys.Onix1/NeuropixelsV2eBno055Data.cs

@@ -23,13 +23,14 @@ public class NeuropixelsV2eBno055Data : Source<Bno055DataFrame>
         public string DeviceName { get; set; }
 
         /// <summary>
-        /// Generates a sequence of <see cref="Bno055DataFrame"/> objects at approximately 100 Hz.
+        /// Generates a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> at approximately 100
+        /// Hz.
         /// </summary>
-        /// <returns>A sequence of <see cref="Bno055DataFrame"/> objects.</returns>
         /// <remarks>
-        /// This will generate a sequence of <see cref="Bno055DataFrame"/> objects at approximately 100 Hz. This rate
-        /// may be limited by the I2C bus.
+        /// This will generate a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> at approximately 100 Hz.
+        /// This rate may be limited by the hardware.
         /// </remarks>
+        /// <returns>A sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see>.</returns>
         public override IObservable<Bno055DataFrame> Generate()
         {
             // Max of 100 Hz, but limited by I2C bus
@@ -38,8 +39,15 @@ public override IObservable<Bno055DataFrame> Generate()
         }
 
         /// <summary>
-        /// Generates a sequence of <see cref="Bno055DataFrame"/> objects.
+        /// Generates a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> that is driven by an
+        /// input sequence.
         /// </summary>
+        /// <remarks>
+        /// This will attempt to produce a sequence of <see cref="Bno055DataFrame">Bno055DataFrames</see> that is updated whenever
+        /// an item in the <paramref name="source"/> sequence is received. This rate is be limited by the
+        /// hardware and has a maximum meaningful rate of 100 Hz.
+        /// </remarks>
+        /// <param name="source">A sequence to drive sampling.</param>
         /// <returns>A sequence of <see cref="Bno055DataFrame"/> objects.</returns>
         public unsafe IObservable<Bno055DataFrame> Generate<TSource>(IObservable<TSource> source)
         {