Apply suggestions from code review Heberto + Zach

Co-authored-by: Heberto Mayorquin <[email protected]>

Author: zm711

neo/rawio/baserawio.py

@@ -90,11 +90,11 @@
     ("name", "U64"),  # not necessarily unique
     ("id", "U64"),  # must be unique
 ]
-
+# To be left an empty array if the concept of buffer is undefined for a reader.
 _signal_stream_dtype = [
     ("name", "U64"),  # not necessarily unique
     ("id", "U64"),  # must be unique
-    ("buffer_id", "U64"), # optional can be ""
+    ("buffer_id", "U64"), # should be "" (empty string) when the stream is not nested under a buffer or the buffer is undefined for some reason.
 ]
 
 _signal_channel_dtype = [

neo/rawio/examplerawio.py

@@ -112,8 +112,8 @@ def _parse_header(self):
         # In short `_parse_header()` can be slow but
         # `_get_analogsignal_chunk()` needs to be as fast as possible
 
-        # create fake signal streams and buffer information
-        # a buffer is a group of channels that are in the same buffer for instance hdf5 or binary : this is optional
+        # create simulated signal streams and buffer information
+        # a buffer is a group of channels that are in the same IO buffer for instance hdf5 or binary that can mapped to with np.memmap : this is optional machinery but must be specified as an empty list if not present
         # a stream is a set channels that need to be grouped : this is mandatory
         # very often streams are similar to buffer
         signal_buffers = []
@@ -149,7 +149,7 @@ def _parse_header(self):
             #  (sampling rate/dtype/t_start/units/...)
             stream_id = str(c // 8)
             # buffer_id indicates optionally if channels are in the same buffer
-            # this is optional. In case the buffer concept do not apply then buffer_id must be ""
+            # this is optional. In case the buffer concept does not apply then buffer_id must be ""
             buffer_id = str(c // 8)
             signal_channels.append((ch_name, chan_id, sr, dtype, units, gain, offset, stream_id, buffer_id))
         signal_channels = np.array(signal_channels, dtype=_signal_channel_dtype)

neo/rawio/plexon2rawio/plexon2rawio.py

@@ -211,7 +211,7 @@ def _parse_header(self):
             buffer_id = ""
             signal_streams.append((stream_name, stream_id, buffer_id))
         signal_streams = np.array(signal_streams, dtype=_signal_stream_dtype)
-        # In plexon buffer is unkown
+        # In plexon buffer is unknown
         signal_buffers = np.array([], dtype=_signal_buffer_dtype)
 
         self._stream_id_samples = {}