Address review comments

OpenEphys.Onix1/StartAcquisition.cs

@@ -14,10 +14,11 @@ namespace OpenEphys.Onix1
     /// specification and API describe a general purpose acquisition system architecture and programming
     /// interface for communication with a host PC. One requirement of ONI is a sequence of events that must
     /// occur in order to start synchronized data acquisition. <see cref="StartAcquisition"/> performs these
-    /// required actions on one or more <see cref="ContextTask"/>s provided in its input sequence. Once
-    /// aquisition is started, devices within a particular context will start to produce data in a format
-    /// called an "ONI frame". The output sequence of this operator is therefore a <see
-    /// cref="GroupedObservable{TKey, TElement}"/>, where
+    /// required actions on one or more <see cref="ContextTask">ContextTasks</see> provided in its input
+    /// sequence. Once acquisition is started, devices managed by a particular <see cref="ContextTask"/> will
+    /// start to produce data in a format called an <see
+    /// href="https://open-ephys.github.io/ONI/api/liboni/oni.html#c.oni_frame_t">ONI frame</see>. The output
+    /// sequence of this operator is therefore a <see cref="IGroupedObservable{TKey, TElement}"/>, where
     /// <list type="table">
     /// <item>
     /// <term>Tkey</term>
@@ -28,11 +29,11 @@ namespace OpenEphys.Onix1
     /// <item>
     /// <term>TElement</term>
     /// <description>
-    /// Is a ONI frame produced by the device with address Tkey.
+    /// Is a ONI Frame produced by the device with address Tkey.
     /// </description>
     /// </item>
     /// </list>
-    /// These pre-sorted frame sequences can be interpreted by downstream data processing operators (e.g. <see
+    /// These pre-sorted frame sequences can be interpreted by downstream Data I/O operators (e.g. <see
     /// cref="BreakoutAnalogInput"/> or <see cref="Bno055Data"/>) that convert ONI frames, which consist of
     /// byte arrays with a header and data block, into data types that are are more amenable to processing
     /// within Bonsai workflows.
@@ -46,12 +47,14 @@ public class StartAcquisition : Combinator<ContextTask, IGroupedObservable<uint,
         /// </summary>
         /// <remarks>
         /// This option allows control over a fundamental trade-off between closed-loop response time and
-        /// overall bandwidth. A minimal value, which is determined by <see
+        /// available bandwidth. A minimal value, which is determined by <see
         /// cref="ContextTask.MaxReadFrameSize"/>, will provide the lowest response latency, so long as data
-        /// can be cleared from hardware memory fast enough to prevent buffering. Larger values will reduce
-        /// system call frequency, increase overall bandwidth, and may improve processing performance for
-        /// high-bandwidth data sources. The optimal value depends on the host computer and hardware
-        /// configuration and must be determined via testing (e.g. using <see cref="MemoryMonitorData"/>).
+        /// can be cleared from hardware memory fast enough to prevent buffering. Larger values will both
+        /// reduce system call frequency and reduce the number of function calls per unit time performed by
+        /// Bonsai, and therefore, increase available bandwidth. Larger values may improve processing
+        /// performance for high-bandwidth data sources. The optimal value depends on the host computer and
+        /// hardware configuration and must be determined via testing (e.g. using <see
+        /// cref="MemoryMonitorData"/>).
         /// </remarks>
         [Description("Number of bytes read per cycle of the acquisition thread.")]
         [Category(DeviceFactory.ConfigurationCategory)]
@@ -61,12 +64,16 @@ public class StartAcquisition : Combinator<ContextTask, IGroupedObservable<uint,
         /// Gets or sets the number of bytes that are pre-allocated for writing data to hardware.
         /// </summary>
         /// <remarks>
-        /// This value determines the amount of memory pre-allocated for calls to <see
+        /// This value determines the amount of memory that is pre-allocated for calls to <see
         /// cref="oni.Context.Write(uint, IntPtr, int)"/>, <see cref="oni.Context.Write{T}(uint, T)"/>, and
-        /// <see cref="oni.Context.Write{T}(uint, T[])"/>. A larger size will reduce the average amount of
-        /// dynamic memory allocation system calls but increase the cost of each of those calls. The minimum
+        /// <see cref="oni.Context.Write{T}(uint, T[])"/>. A larger size will reduce the frequency of
+        /// dynamic memory allocation system calls but increase the expense of each of those calls. The minimum
         /// size of this option is determined by <see cref="ContextTask.MaxWriteFrameSize"/>. The effect on
-        /// real-timer performance is not as large as that of <see cref="ContextTask.BlockReadSize"/>.
+        /// real-time performance is typically not as large as that of <see cref="ContextTask.BlockReadSize"/>
+        /// because this parameter defines a readily-available pool of memory for the creation of output data
+        /// frames, but does not determine when they are written to hardware. Data is written to hardware as
+        /// soon as an output frame has been created. In contrast data is read from hardware whenever more than
+        /// <see cref="ReadSize"/> bytes have accumulated in the input buffer.
         /// </remarks>
         [Description("The number of bytes that are pre-allocated for writing data to hardware.")]
         [Category(DeviceFactory.ConfigurationCategory)]