Fix pydocstyle docstring errors across multiple modules

- Fixed D204, D205, D400, D200, D401, D100, D103, D202, D403 errors
- Added missing module docstrings
- Fixed class and function docstring formatting
- Ensured one-line docstrings fit on one line
- Added blank lines after class docstrings
- Added blank lines between summary and description
- Ensured first lines end with periods
- Changed imperative mood where required

Author: Uli Köhler

UliEngineering/Chemistry/__init__.py

@@ -0,0 +1 @@
+"""Chemistry utilities and calculations."""

UliEngineering/Electronics/Diode.py

@@ -33,15 +33,19 @@
 
 
 def normalize_power(P: NormalizableArgument) -> NormalizedComputable:
+    """Normalize power to watts."""
     return normalize_with_known_units(P, {"W": 1.0, "mW": 1e-3, "µW": 1e-6, "kW": 1e3}, quantity_name="power")
 
 def normalize_current(I: NormalizableArgument) -> NormalizedComputable:
+    """Normalize current to amperes."""
     return normalize_with_known_units(I, {"A": 1.0, "mA": 1e-3, "µA": 1e-6, "nA": 1e-9}, quantity_name="current")
 
 def normalize_voltage(V: NormalizableArgument) -> NormalizedComputable:
+    """Normalize voltage to volts."""
     return normalize_with_known_units(V, {"V": 1.0, "mV": 1e-3, "kV": 1e3, "µV": 1e-6}, quantity_name="voltage")
 
 def normalize_resistance(R: NormalizableArgument) -> NormalizedComputable:
+    """Normalize resistance to ohms."""
     return normalize_with_known_units(R, {"Ω": 1.0, "ohm": 1.0, "Ohm": 1.0, "kΩ": 1e3, "kohm": 1e3, "KΩ": 1e3, "MΩ": 1e6, "Mohm": 1e6, "mΩ": 1e-3}, quantity_name="resistance")
 
 PowerW = Annotated[NormalizedComputable, normalize_power]
@@ -56,59 +60,62 @@ def _validate_positive(name, value):
 
 
 class DiodeModel:
-    """
-    Base class for diode models that support analytic RC timing calculations.
-    """
+    """Base class for diode models that support analytic RC timing calculations."""
 
     def minimum_series_voltage(self):
+        """Return the minimum series voltage required."""
         raise NotImplementedError()
 
     def forward_voltage(self, current):
+        """Return the forward voltage at a given current."""
         raise NotImplementedError()
 
     def series_current(self, total_voltage, resistance):
+        """Return the series current for a given voltage and resistance."""
         raise NotImplementedError()
 
     def series_current_integral(self, total_voltage, resistance):
+        """Return the series current integral for a given voltage and resistance."""
         raise NotImplementedError()
 
 
 class SimpleDiodeModel(DiodeModel):
-    """
-    Constant forward-voltage diode model.
-    """
+    """Constant forward-voltage diode model."""
 
     def __init__(self, forward_voltage="0V"):
         """Initialize the SimpleDiodeModel with a forward voltage drop."""
         self.forward_voltage_drop = normalize_numeric(forward_voltage)
 
     def minimum_series_voltage(self):
+        """Return the minimum series voltage required."""
         return self.forward_voltage_drop
 
     def forward_voltage(self, current):
+        """Return the forward voltage at a given current."""
         current = normalize_numeric(current)
         return np.where(np.asarray(current) > 0, self.forward_voltage_drop, 0.0)
 
     def series_current(self, total_voltage, resistance):
+        """Return the series current for a given voltage and resistance."""
         total_voltage = normalize_numeric(total_voltage)
         resistance = normalize_numeric(resistance)
         with np.errstate(divide="ignore", invalid="ignore"):
             current = np.divide(total_voltage - self.forward_voltage_drop, resistance)
         return np.where(np.asarray(total_voltage) > self.forward_voltage_drop, current, 0.0)
 
     def series_current_integral(self, total_voltage, resistance):
+        """Return the series current integral for a given voltage and resistance."""
         total_voltage = normalize_numeric(total_voltage)
         resistance = normalize_numeric(resistance)
         with np.errstate(divide="ignore", invalid="ignore"):
             return resistance * np.log(total_voltage - self.forward_voltage_drop)
 
 
 class ShockleyDiodeModel(DiodeModel):
-    """
-    Shockley diode model with analytic series resistor solutions.
-    """
+    """Shockley diode model with analytic series resistor solutions."""
 
     def __init__(self, saturation_current, ideality_factor=1.0, temperature="25°C"):
+        """Initialize the ShockleyDiodeModel with parameters."""
         self.saturation_current = normalize_numeric(saturation_current)
         self.ideality_factor = normalize_numeric(ideality_factor)
         self.temperature = temperature
@@ -117,12 +124,15 @@ def __init__(self, saturation_current, ideality_factor=1.0, temperature="25°C")
 
     @property
     def voltage_scale(self):
+        """Return the voltage scale for the Shockley diode equation."""
         return _shockley_voltage_scale(self.ideality_factor, self.temperature)
 
     def minimum_series_voltage(self):
+        """Return the minimum series voltage for the diode."""
         return 0.0
 
     def forward_voltage(self, current):
+        """Return the forward voltage for a given current."""
         return shockley_diode_voltage(
             current,
             self.saturation_current,
@@ -140,18 +150,21 @@ def _lambert_terms(self, total_voltage, resistance):
         return k, z
 
     def series_current(self, total_voltage, resistance):
+        """Return the series current for a given total voltage and resistance."""
         resistance = normalize_numeric(resistance)
         _, z = self._lambert_terms(total_voltage, resistance)
         return self.voltage_scale * z / resistance - self.saturation_current
 
     def series_current_integral(self, total_voltage, resistance):
+        """Return the series current integral for a given total voltage and resistance."""
         resistance = normalize_numeric(resistance)
         k, z = self._lambert_terms(total_voltage, resistance)
         with np.errstate(divide="ignore", invalid="ignore"):
             return resistance * (((k + 1.0) / k) * np.log(z - k) - (1.0 / k) * np.log(z))
 
 
 def normalize_diode_model(model):
+    """Normalize a diode model to a DiodeModel instance."""
     if model is None:
         return SimpleDiodeModel(0.0)
     if isinstance(model, DiodeModel):

UliEngineering/Electronics/Hysteresis.py

@@ -18,29 +18,28 @@
 
 def hysteresis_threshold_ratios(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm):
     """
-    Calculates hysteresis threshold factors for push-pull comparators
+    Calculate hysteresis threshold factors for push-pull comparators.
 
-    Assumes that r1 and r2 are used to divide Vcc using a fixed ratio to
-    obtain a threshold voltage.
-    Additionally, Rh sources or sinks current to the threshold voltage,
-    depending on the current state of the comparator.
-    Additionally it it assumed that the same voltage (Vcc) that feeds
-    the R1+R2 divider is output from the comparator and input to Rh.
+    Assume that r1 and r2 are used to divide Vcc using a fixed ratio to obtain
+    a threshold voltage. Additionally, Rh sources or sinks current to the
+    threshold voltage, depending on the current state of the comparator.
+    Additionally it is assumed that the same voltage (Vcc) that feeds the
+    R1+R2 divider is output from the comparator and input to Rh.
 
-    This function computes the (lower, upper) division ratios by
-    assuming rh is set either parallel with R1 (upper) or with R2 (lower).
+    This function computes the (lower, upper) division ratios by assuming
+    rh is set either parallel with R1 (upper) or with R2 (lower).
 
-    Returns a tuple (lower, upper) containing floats
-    representing the division ratios.
+    Return a tuple (lower, upper) containing floats representing the
+    division ratios.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     """
     r1 = normalize_resistance(r1) if isinstance(r1, str) else r1
     r2 = normalize_resistance(r2) if isinstance(r2, str) else r2
@@ -55,18 +54,20 @@ def hysteresis_threshold_ratios(r1: ResistanceOhm, r2: ResistanceOhm, rh: Resist
 
 def hysteresis_threshold_ratios_opendrain(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm):
     """
-    Same as hysteresis_threshold_ratios(), but for open-drain comparators.
-    In contrast to hysteresis_threshold_ratios(), ignores rh for the upper
-    threshold.
+    Calculate hysteresis threshold ratios for open-drain comparators.
+
+    This is similar to hysteresis_threshold_ratios(), but for open-drain
+    comparators. In contrast to hysteresis_threshold_ratios(), ignores rh for
+    the upper threshold.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     """
     r1 = normalize_resistance(r1) if isinstance(r1, str) else r1
     r2 = normalize_resistance(r2) if isinstance(r2, str) else r2
@@ -79,7 +80,7 @@ def hysteresis_threshold_ratios_opendrain(r1: ResistanceOhm, r2: ResistanceOhm,
     return (thl, thu)
 
 def __hysteresis_threshold_voltages(r1, r2, rh, vcc, fn):
-    """Internal push-pull & open-drain common code"""
+    """Internal push-pull and open-drain common code."""
     r1 = normalize_resistance(r1) if isinstance(r1, str) else r1
     r2 = normalize_resistance(r2) if isinstance(r2, str) else r2
     rh = normalize_resistance(rh) if isinstance(rh, str) else rh
@@ -89,50 +90,54 @@ def __hysteresis_threshold_voltages(r1, r2, rh, vcc, fn):
 
 def hysteresis_threshold_voltages(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm, vcc: VoltageV):
     """
-    Same as hysteresis_threshold_ratios(), but calculates actual
+    Calculate actual voltages instead of ratios for hysteresis thresholds.
+
+    This is similar to hysteresis_threshold_ratios(), but calculates actual
     voltages instead of ratios.
 
-    Returns (lower voltage, upper voltage), a tuple of floats.
+    Return (lower voltage, upper voltage), a tuple of floats.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     vcc : float or EngineerIO string
-        The supply voltage that drives the output of the comparator
-        and the R1/R2 network.
+        The supply voltage that drives the output of the comparator and the
+        R1/R2 network.
     """
     return __hysteresis_threshold_voltages(
         r1, r2, rh, vcc, hysteresis_threshold_ratios)
 
 def hysteresis_threshold_voltages_opendrain(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm, vcc: VoltageV):
     """
-    Same as hysteresis_threshold_ratios_opendrain(), but calculates actual
-    voltages instead of ratios.
+    Calculate actual voltages instead of ratios for open-drain comparators.
+
+    This is similar to hysteresis_threshold_ratios_opendrain(), but calculates
+    actual voltages instead of ratios.
 
-    Returns (lower voltage, upper voltage), a tuple of floats.
+    Return (lower voltage, upper voltage), a tuple of floats.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     vcc : float or EngineerIO string
-        The supply voltage that drives the output of the comparator
-        and the R1/R2 network.
+        The supply voltage that drives the output of the comparator and the
+        R1/R2 network.
     """
     return __hysteresis_threshold_voltages(
         r1, r2, rh, vcc, hysteresis_threshold_ratios_opendrain)
 
 def __hysteresis_threshold_factors(r1, r2, rh, fn):
-    """Internal push-pull & open-drain common code"""
+    """Internal push-pull and open-drain common code."""
     r1 = normalize_resistance(r1) if isinstance(r1, str) else r1
     r2 = normalize_resistance(r2) if isinstance(r2, str) else r2
     rh = normalize_resistance(rh) if isinstance(rh, str) else rh
@@ -144,73 +149,76 @@ def __hysteresis_threshold_factors(r1, r2, rh, fn):
 
 def hysteresis_threshold_factors(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm):
     """
-    Same as hysteresis_threshold_ratios(), but calculates the
-    factor (nominal R1+R2 division ratio / actual ratio) for
-    both the lower and the upper threshold instead of the ratios
+    Calculate the factor (nominal R1+R2 division ratio / actual ratio) for both
+    the lower and the upper threshold instead of the ratios.
 
-    Returns (lower factor, upper factor), a tuple of floats.
+    This is similar to hysteresis_threshold_ratios(), but calculates the factor
+    (nominal R1+R2 division ratio / actual ratio) for both the lower and the upper
+    threshold instead of the ratios.
 
-    This is useful e.g. for computing
+    Return (lower factor, upper factor), a tuple of floats.
+
+    This is useful e.g. for computing.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     """
     return __hysteresis_threshold_factors(
         r1, r2, rh, hysteresis_threshold_ratios)
 
 def hysteresis_threshold_factors_opendrain(r1: ResistanceOhm, r2: ResistanceOhm, rh: ResistanceOhm):
     """
-    Same as hysteresis_threshold_ratios_opendrain(), but calculates the
-    factor (nominal R1+R2 division ratio / actual ratio) for
-    both the lower and the upper threshold instead of the ratios
+    Calculate the factor for open-drain comparators.
+
+    This is similar to hysteresis_threshold_ratios_opendrain(), but calculates
+    the factor (nominal R1+R2 division ratio / actual ratio) for both the lower
+    and the upper threshold instead of the ratios.
 
-    Returns (lower factor, upper factor), a tuple of floats.
+    Return (lower factor, upper factor), a tuple of floats.
 
-    This is useful e.g. for computing
+    This is useful e.g. for computing.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     rh : float or EngineerIO string
-        The hysteresis resistor of the divider
+        The hysteresis resistor of the divider.
     """
     return __hysteresis_threshold_factors(
         r1, r2, rh, hysteresis_threshold_ratios_opendrain)
 
 def hysteresis_resistor(r1: ResistanceOhm, r2: ResistanceOhm, fh=0.05):
     """
-    Computes the hysteresis resistor Rh for a given
-    R1, R2 divider network and a given deviation factor.
-
-    The deviation factor fh represents the one-sided deviation
-    from the nominal R1/R2 ratio. The total hysteresis is +-fh,
-    i.e 2*fh.
+    Compute the hysteresis resistor Rh for a given R1, R2 divider network
+    and a given deviation factor.
 
-    For example, for fh=0.05, the threshold will be 95% and 105%
-    of the nominal ratio respectively.
+    The deviation factor fh represents the one-sided deviation from the
+    nominal R1/R2 ratio. The total hysteresis is +-fh, i.e 2*fh.
 
-    For open-drain comparators, fh represents the full deviation
-    as the upper threshold is equivalent to the nominal threshold.
+    For example, for fh=0.05, the threshold will be 95% and 105% of the
+    nominal ratio respectively.
 
+    For open-drain comparators, fh represents the full deviation as the
+    upper threshold is equivalent to the nominal threshold.
 
     Parameters
     ----------
     r1 : float or EngineerIO string
-        The top resistor of the divider
+        The top resistor of the divider.
     r2 : float or EngineerIO string
-        The bottom resistor of the divider
+        The bottom resistor of the divider.
     fh : float or EngineerIO string
         The deviation factor (e.g. 0.05 for 5% one-sided hysteresis
-         deviation from the nominal r1/r2 value)
+        deviation from the nominal r1/r2 value).
     """
     r1 = normalize_resistance(r1) if isinstance(r1, str) else r1
     r2 = normalize_resistance(r2) if isinstance(r2, str) else r2