some polishing of comments and help texts

Author: mfg92

csvexport.py

@@ -405,64 +405,64 @@ def channel_type(value):
     command_group.add_argument(metavar='csv_path', dest='csv_path', nargs='?',
                                type=str, default=None,
                                help='Exports measured data to the given file in CSV format.'
-                                    " If filename ends with '.xz' the content is compress using lzma/xz."
-                                    " This reduces the filesize to ~ 1/12 compered to the uncompressed format."
-                                    " Those files can be decompressed using 'xz -dk <filename>")
+                                    " If the filename ends with '.xz' the content is compressed using lzma/xz."
+                                    " This reduces the file size to ~ 1/12 compared to the uncompressed format."
+                                    " Those files can be decompressed using 'xz -dk <filename>'.")
     command_group.add_argument('--calibrate', metavar=('calibrationfile_path', 'channels_at_once'), nargs=2,
                                type=str, default=None,
                                help='If set, calibrate the device by measuring given voltages and write'
                                     ' calibration values to given file.'
-                                    ' Multiple channels (1, 2, 4 or all 8) can get calibrated at the same time'
+                                    ' Multiple channels (1, 2, 4 or all 8) can be calibrated at the same time'
                                     ' if supplied with the same voltage. Ignores all other arguments.')
     parser.add_argument('-s', '--channels', metavar='channel', nargs='+',
                         type=channel_type, default=list(range(1, 9)),
-                        help="Select channels that are of interest")
+                        help="Selects channels of interest.")
     parser.add_argument('-l', '--loglevel', dest='log_level', nargs='?',
                         type=str, default="info", choices=str_to_log_level.keys(),
-                        help='Set the loglevel to debug')
+                        help='Sets the log level for debugging.')
     parser.add_argument('-v', '--vscale', metavar='scale', nargs="+",
                         type=float, default=[1.0], choices=Hantek1008.valid_vscale_factors(),
-                        help='Set the pre scale in the hardware, must be 1, 0.125, or 0.02. If one value is given, all '
-                             'selected channels will use that vscale, otherwise there must be one value per selected'
-                             'channel')
+                        help='Sets the pre scale in the hardware, must be 1, 0.125, or 0.02. If a single value is '
+                             'given, all selected channels will use that vscale, otherwise there must be one value '
+                             'per selected channel.')
     parser.add_argument('-c', '--calibrationfile', dest="calibration_file_path", metavar='calibrationfile_path',
                         type=str, default=None,
-                        help="Use the content of the given calibration file to correct the measured samples")
+                        help="Use the content of the given calibration file to correct the measured samples.")
     parser.add_argument('-r', '--raw', dest="raw_or_volt",
                         type=str, default="volt", const="raw", nargs='?', choices=["raw", "volt", "volt+raw"],
-                        help="Specifies whether the sample values return from the device should be transformed"
-                             " to volts (eventually using calibration data) or not. If flag is not set, it defaults"
-                             " to 'volt'. If flag is set without a parameter 'raw' is used")
+                        help="Specifies whether the sample values returned from the device should be transformed "
+                             "to volts (using calibration data if specified) or not. If not set, the default "
+                             "value is 'volt'. If the flag is set without a parameter, 'raw' is used.")
     parser.add_argument('-z', '--zoscompensation', dest="zos_compensation", metavar='x',
                         type=str, default=None, nargs='*',
                         help=
-                        """Compensate the zero offset shift that obscures over longer timescales.
+                        """Compensates the zero offset shift that occurs over longer timescales.
                         There are two possible ways of compensating that:
-                        (A) Compute shift out of an unused channels: Needs at least one unused channel, make sure
-                         that no voltage is applied to the given channel. 
-                        (B) Compute shift with the help of a given function. Such a function computes a correction-factor
-                         based on the time past since start.
-                        Defaults to no compensation. If used without an argument method A is used on channel 8.
-                        If one integer argument is given method A is used on that channel. Otherwise Method B is used.
-                        It awaits a path to a file with a python function 
+                        (A) Computing the shift out of an unused channel: Needs at least one unused channel, make sure
+                         that no external voltage is applied to the given channel. 
+                        (B) Computing the shift with the help of a given function. Such a function computes a 
+                         correction-factor based on the time passed since start.
+                        Defaults to no compensation. If used without an argument, method A is used on channel 8.
+                        If an integer argument is given, method A is used on that channel. Otherwise, method B is used,
+                        which expects a path to a python file with containing a function 
                         (calc_zos(ch: int, vscale: float, dtime: float)->float) in it 
                         and as a second argument a time offset (how long the device is already running in sec).
                         """)
     parser.add_argument('-f', '--samplingrate', dest='sampling_rate',
                         type=float, default=440, choices=Hantek1008.valid_roll_sampling_rates(),
-                        help='Set the sampling rate (in Hz) the device should use (default:440)')
+                        help='Sets the sampling rate (in Hz) the device should use (default:440).')
     parser.add_argument('-m', '--measuresamplingrate', dest='do_sampling_rate_measure', action="store_const",
                         default=False, const=True,
-                        help='Measure the exact samplingrate the device achieves by using the computer internal clock.'
-                             'Increases startup duration by ~10 sec')
+                        help='Measures the exact sampling rate the device achieves by using the computer internal '
+                             'clock. Increases startup duration by ~10 sec.')
     parser.add_argument('-t', '--timestampstyle', dest="timestamp_style",
                         type=str, default="own_row", nargs='?', choices=["own_row", "first_column"],
-                        help="Specifies the style the timestamps of the values are included in the CSV output. There"
+                        help="Specifies the style of the timestamps included in the CSV output. There"
                              " are two options: When the 'own_row' style is used, every time the device sends a bunch"
-                             " of measured samples, these are writen to the CSV output followed by one row with the"
+                             " of measured samples, these are written to the CSV output followed by one row with the"
                              " timestamp."
-                             " Use the 'first_column' option to let the first column have interpolated timestamps."
-                             " Default is 'own_row'.")
+                             " Use the 'first_column' option to let the first column of each line have an interpolated"
+                             " timestamp. Default is 'own_row'.")
 
     args = parser.parse_args()
 

hantek1008.py

@@ -10,9 +10,9 @@
 import copy
 import sys
 
-# marking a child classes method with overrides makes sure the method overrides a parent class method
-# this check is only needed during development so its no problem if this package is not installed
-# to avoid errors we need to define a dummy decorator
+# marking a child class method with overrides makes sure the method overrides a parent class method.
+# this check is only needed during development so its no problem if this package is not installed.
+# to avoid errors, we need to define a dummy decorator.
 try:
     from overrides import overrides
 except ImportError:
@@ -35,7 +35,7 @@ class Hantek1008Raw:
     """
     This class communicates to a Hantek1008 device via USB.
     It supports configuring the device (set vertical scale, sampling frequency, waveform generator,..)
-    and measure samples with it. Either in continuous (rolling) mode or in windows (normal/burst) mode.
+    and measuring samples with it. Either in continuous (rolling) mode or in windows (normal/burst) mode.
     """
     # channel_id/channel_index are zero based
     # channel names are one based
@@ -52,20 +52,20 @@ def __init__(self, ns_per_div: int = 500_000,
                  vertical_scale_factor: Union[float, List[float]] = 1.0) -> None:
         """
         :param ns_per_div:
-        :param vertical_scale_factor: must be an array of length 8 with a float scale value for each channel.
-        Or a single float, than all channel will have that scale factor. The float must be 1.0, 0.2 or 0.02.
+        :param vertical_scale_factor: must be an array of length 8 with a float scale value for each channel
+               or a single float scale factor applied to all channels. The float must be either 1.0, 0.2 or 0.02.
         """
 
         assert isinstance(vertical_scale_factor, float) or len(vertical_scale_factor) == Hantek1008Raw.channel_count()
 
-        self.__ns_per_div: int = ns_per_div  # on value for all channels
+        self.__ns_per_div: int = ns_per_div  # one value for all channels
 
         # one vertical scale factor (float) per channel
         self.__vertical_scale_factors: List[float] = [vertical_scale_factor] * Hantek1008Raw.channel_count() \
             if isinstance(vertical_scale_factor, float) \
             else copy.deepcopy(vertical_scale_factor)  # scale factor per channel
 
-        # dict of list of shorts, outer dict is of size 3 and contains values
+        # dict of list of floats, outer dict is of size 3 and contains values
         # for every vertical scale factor, inner list contains an zero offset per channel
         self._zero_offsets: Dict[float, List[float]] = None
 
@@ -79,7 +79,7 @@ def __init__(self, ns_per_div: int = 500_000,
         self.__cancel_pause_thread: bool = False
 
     def connect(self):
-        """Find a plugged hantek 1008c device and set up the connection to it"""
+        """Find a plugged in hantek 1008c device and set up the connection to it"""
 
         self._dev = usb.core.find(idVendor=0x0783, idProduct=0x5725)
 
@@ -91,15 +91,16 @@ def connect(self):
         # configuration will be the active one
         self._dev.set_configuration()
 
-        # get an endpoint instance
         self._cfg = self._dev.get_active_configuration()
         self._intf = self._cfg[(0, 0)]
 
+        # get an output endpoint instance
         self.__out = usb.util.find_descriptor(
             self._intf,
             # match the first OUT endpoint
             custom_match=lambda e: usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT)
 
+        # get an input endpoint instance
         self.__in = usb.util.find_descriptor(
             self._intf,
             # match the first IN endpoint
@@ -110,7 +111,7 @@ def connect(self):
 
     def __write_and_receive(self, message: bytes, response_length: int,
                             sec_till_response_request: float = 0.002, sec_till_start: float = 0.002) -> bytes:
-        """write and read from the device"""
+        """write to and read from the device"""
         start_time = time.time()
 
         assert isinstance(message, bytes)
@@ -152,8 +153,8 @@ def __send_cmd(self, cmd_id: int, parameter: Union[bytes, List[int], str] = b'',
             return response
 
     def __send_c6_a6_command(self, parameter: int) -> bytes:
-        """send the c602 or c603 command, then parse the response as sample_length. then follow CEIL(sample_length/64)
-        a602 or a603 request. The responses are concatenated and finally returned trimmed to the fit the sample_length.
+        """send the c602 or c603 command, then parse the response as sample_length. then CEIL(sample_length/64)
+        a602 or a603 requests follow. The responses are concatenated and finally returned trimmed to fit the sample_length.
         """
         assert parameter in [2, 3]
         response = self.__send_cmd(0xc6, parameter=[parameter], response_length=2, echo_expected=False)
@@ -507,7 +508,7 @@ def compute_pulse_length(speed_in_rpm: int, bits_per_wave: int = 8) -> int:
 
     def set_generator_waveform(self, waveform: List[int]) -> None:
         """
-        Every Byte in the waveform list contains information vor every of the 8 digital ouputs to be on or of.
+        Every Byte in the waveform list contains information for every of the 8 digital ouputs to be on or of.
         The bit number i in one of those bytes tells if output i should be on or off in that part of the wave.
         :param waveform:
         :return: