docstrings & black

mhkit/dolfyn/io/base.py

@@ -114,9 +114,22 @@ def _handle_nan(data):
 
 def _remove_gps_duplicates(dat):
     """
-    Removes duplicate and nan timestamp values in 'time_gps' coordinate,
-    and add hardware (ADCP DAQ) timestamp corresponding to GPS acquisition
-    (in addition to the GPS unit's timestamp).
+    Removes duplicate and NaN timestamp values in the 'time_gps' coordinate
+    of the dataset and adds a hardware (ADCP DAQ) timestamp corresponding to GPS
+    acquisition in the 'hdwtime_gps' variable.
+
+    Parameters
+    ----------
+    dat : xarray.Dataset
+        Dataset containing GPS-related data and timestamps. This dataset is
+        modified in place.
+
+    Returns
+    -------
+    xarray.Dataset
+        The input dataset with duplicates and NaN values removed from the
+        'time_gps' coordinate. A new variable, 'hdwtime_gps', is added to
+        indicate the hardware timestamp corresponding to GPS acquisition.
     """
 
     dat["data_vars"]["hdwtime_gps"] = dat["coords"]["time"]

mhkit/dolfyn/io/nortek_lib.py

@@ -6,8 +6,21 @@
 
 
 def _bcd2char(cBCD):
-    """Taken from the Nortek System Integrator Manual
-    "Example Program" Chapter.
+    """
+    Converts a Binary-Coded Decimal (BCD) value to a character integer.
+
+    This method is based on the Nortek System Integrator Manual's example
+    program and ensures that values do not exceed 153.
+
+    Parameters
+    ----------
+    cBCD : int
+        BCD-encoded integer.
+
+    Returns
+    -------
+    int
+        The decoded integer from BCD format.
     """
     cBCD = min(cBCD, 153)
     c = cBCD & 15
@@ -16,23 +29,80 @@ def _bcd2char(cBCD):
 
 
 def _bitshift8(val):
+    """
+    Performs an 8-bit right bit shift on an integer value.
+
+    Parameters
+    ----------
+    val : int
+        The value to shift.
+
+    Returns
+    -------
+    int
+        The integer result after shifting right by 8 bits.
+    """
     return val >> 8
 
 
 def _int2binarray(val, n):
+    """
+    Converts an integer to a binary array of length `n`.
+
+    Parameters
+    ----------
+    val : int
+        Integer to convert to binary.
+    n : int
+        Length of the output binary array.
+
+    Returns
+    -------
+    np.ndarray
+        Binary array of boolean values representing the integer.
+    """
     out = np.zeros(n, dtype="bool")
     for idx, n in enumerate(range(n)):
         out[idx] = val & (2**n)
     return out
 
 
 def _crop_data(obj, range, n_lastdim):
+    """
+    Crops data in a dictionary of arrays based on the specified range.
+
+    Parameters
+    ----------
+    obj : dict
+        Dictionary containing data arrays.
+    range : slice
+        The range to crop the last dimension of each array.
+    n_lastdim : int
+        The size of the last dimension to check for cropping eligibility.
+
+    Notes
+    -----
+    Modifies `obj` in place by cropping the last dimension of arrays.
+    """
     for nm, dat in obj.items():
         if isinstance(dat, np.ndarray) and (dat.shape[-1] == n_lastdim):
             obj[nm] = dat[..., range]
 
 
 def _recatenate(obj):
+    """
+    Concatenates data from a list of dictionaries along the last axis.
+
+    Parameters
+    ----------
+    obj : list of dict
+        List of dictionaries to concatenate.
+
+    Returns
+    -------
+    dict
+        A dictionary with concatenated values across the list.
+    """
     out = type(obj[0])()
     for ky in list(obj[0].keys()):
         if ky in ["__data_groups__", "_type"]:
@@ -46,7 +116,25 @@ def _recatenate(obj):
 
 
 def rd_time(strng):
-    """Read the time from the first 6bytes of the input string."""
+    """
+    Reads the time from the first 6 bytes of a binary string.
+
+    Parameters
+    ----------
+    strng : bytes
+        A byte string where the first 6 bytes encode the time.
+
+    Returns
+    -------
+    float
+        The epoch time extracted from the input byte string.
+
+    Notes
+    -----
+    Uses BCD conversion to extract year, month, day, hour, minute, and
+    second from the byte string, then converts to an epoch time.
+    """
+
     min, sec, day, hour, year, month = unpack("BBBBBB", strng[:6])
     return time.date2epoch(
         datetime(

mhkit/dolfyn/io/rdi.py

@@ -701,7 +701,17 @@ def read_nocode(self, id):
             self.skip_nocode(id)
 
     def skip_nocode(self, id):
-        """Skip bytes if ID is not in function map"""
+        """
+        Skips bytes when an ID code is not found in the function map.
+
+        This method calculates the byte length to skip based on the positions
+        of known ID codes and uses this length to bypass filler or irrelevant data.
+
+        Parameters
+        ----------
+        id : int
+            The ID code that is not present in the function map.
+        """
         offsets = list(self.id_positions.values())
         idx = np.where(offsets == self.id_positions[id])[0][0]
         byte_len = offsets[idx + 1] - offsets[idx] - 2
@@ -712,8 +722,19 @@ def skip_nocode(self, id):
 
     def check_offset(self, offset, readbytes):
         """
-        Check distance to nearest function ID and adjust file
-        position as necessary
+        Checks and adjusts the file position based on the distance to the nearest function ID.
+
+        If the provided `offset` differs from the expected value and `_fixoffset` is zero,
+        this method updates `_fixoffset` and adjusts the file position in the data file
+        (`self.f`) accordingly. This adjustment is logged if `_debug_level` is set to a
+        positive value.
+
+        Parameters
+        ----------
+        offset : int
+            The current offset from the expected position.
+        readbytes : int
+            The number of bytes that have been read so far.
         """
         fd = self.f
         if offset != 4 and self._fixoffset == 0: