Add unique documentation to Generate() overrides

Author: jonnew

OpenEphys.Onix1/BreakoutAnalogOutput.cs

@@ -39,8 +39,14 @@ public class BreakoutAnalogOutput : Sink<Mat>
         public BreakoutAnalogIODataType DataType { get; set; } = BreakoutAnalogIODataType.S16;
 
         /// <summary>
-        /// Send samples to analog outputs.
+        /// Send a matrix of samples to analog outputs
         /// </summary>
+        /// <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 <see
+        /// cref="DataType"/> is set to <see cref="BreakoutAnalogIODataType.S16"/> or <see cref="Depth.F32"/>
+        /// when <see cref="DataType"/> 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)
@@ -103,8 +109,13 @@ 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 analog outputs.
         /// </summary>
+        /// <remarks>
+        /// This overload should be used when <see cref="DataType"/> 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)
@@ -130,8 +141,12 @@ public IObservable<short[]> Process(IObservable<short[]> source)
         }
 
         /// <summary>
-        /// Send samples to analog outputs.
+        /// Send an 12-element array of values to update all analog outputs.
         /// </summary>
+        /// <remarks>
+        /// This overload should be used when <see cref="DataType"/> 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)

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)
         {