Fix and improve docstrings

src/frequenz/client/common/metrics/_sample.py

@@ -127,8 +127,8 @@ class MetricSample:
     """A sampled metric.
 
     This represents a single sample of a specific metric, the value of which is either
-    measured at a particular time. The real-time system-defined bounds are optional and
-    may not always be present or set.
+    measured or derived at a particular time. The real-time system-defined bounds are
+    optional and may not always be present or set.
 
     Note: Relationship Between Bounds and Metric Samples
         Suppose a metric sample for active power has a lower-bound of -10,000 W, and an
@@ -142,8 +142,6 @@ class MetricSample:
     metric: Metric | int
     """The metric that was sampled."""
 
-    # In the protocol this is float | AggregatedMetricValue, but for live data we can't
-    # receive the AggregatedMetricValue, so we limit this to float for now.
     value: float | AggregatedMetricValue | None
     """The value of the sampled metric."""
 
@@ -177,11 +175,11 @@ class MetricSample:
     """
 
     connection: MetricConnection | None = None
-    """The electrical connection within the component from which the metric was sampled.
+    """The specific source or connection from which the metric was sampled.
 
-    This will be present when the same `Metric` can be obtained from multiple electrical
-    connections within the component. Knowing the connection can help in certain control
-    and monitoring applications.
+    This will be present when the same `Metric` can be obtained from multiple sources or
+    connections. Knowing the connection can help in certain control and monitoring
+    applications.
 
     In cases where the component has just one connection for a metric, then the
     connection is `None`.

src/frequenz/client/common/microgrid/electrical_components/_category.py

@@ -11,11 +11,7 @@ class ElectricalComponentCategory(enum.Enum):
     """Possible types of microgrid electrical component."""
 
     UNSPECIFIED = 0
-    """An unknown component category.
-
-    Useful for error handling, and marking unknown components in
-    a list of components with otherwise known categories.
-    """
+    """The component category is unspecified. This should not be used."""
 
     GRID_CONNECTION_POINT = 1
     """The point where the local microgrid is connected to the grid."""
@@ -24,25 +20,28 @@ class ElectricalComponentCategory(enum.Enum):
     """A meter, for measuring electrical metrics, e.g., current, voltage, etc."""
 
     INVERTER = 3
-    """An electricity generator, with batteries or solar energy."""
+    """An inverter that converts DC to AC power and vice versa."""
 
     CONVERTER = 4
     """An electricity converter, e.g., a DC-DC converter."""
 
     BATTERY = 5
-    """A storage system for electrical energy, used by inverters."""
+    """A battery energy storage system."""
 
     EV_CHARGER = 6
     """A station for charging electrical vehicles."""
 
     BREAKER = 7
-    """A relay, used for switching electrical circuits on and off."""
+    """A circuit breaker, providing protection and switching by disconnecting circuits."""
 
     PRECHARGER = 8
     """A precharger, used for preparing electrical circuits for switching on."""
 
     CHP = 9
-    """A heat and power combustion plant (CHP stands for combined heat and power)."""
+    """A combined heat and power (CHP) plant.
+
+    It generates electricity and useful heat from a single energy source.
+    """
 
     ELECTROLYZER = 10
     """A device for splitting water into hydrogen and oxygen using electricity."""

src/frequenz/client/common/microgrid/electrical_components/_diagnostic_code.py

@@ -53,7 +53,7 @@ class ElectricalComponentDiagnosticCode(enum.Enum):
     """The component's precharge unit has failed."""
 
     PLAUSIBILITY_ERROR = 13
-    """Plausibility issues within the system involving this component."""
+    """Plausibility issues within the component, causing its internal sanity checks to fail."""
 
     FAULT_CURRENT = 14
     """Fault current detected in the component."""
@@ -77,10 +77,13 @@ class ElectricalComponentDiagnosticCode(enum.Enum):
     """The component is unauthorized to perform the last requested action."""
 
     EXCESS_LEAKAGE_CURRENT = 21
-    """Excess leakage current was detected in the component."""
+    """Excess leakage current detected, over the threshold defined by the manufacturer."""
 
     LOW_SYSTEM_INSULATION_RESISTANCE = 22
-    """Low system insulation resistance detected in the component."""
+    """The component is inoperable due to the insulation resistance being too low.
+
+    The threshold is defined by the manufacturer or configured by the user.
+    """
 
     GROUND_FAULT = 23
     """Ground fault detected in the component."""
@@ -98,25 +101,32 @@ class ElectricalComponentDiagnosticCode(enum.Enum):
     """The component performed a protective shutdown."""
 
     GRID_OVERVOLTAGE = 30
-    """The grid voltage is over the maximum rated value."""
+    """The component is inoperable due to the grid voltage being too high."""
 
     GRID_UNDERVOLTAGE = 31
-    """The grid voltage is under the minimum rated value."""
+    """The component is inoperable due to the grid voltage being too low."""
 
     GRID_OVERFREQUENCY = 32
-    """The grid frequency is over the maximum rated value."""
+    """The component is inoperable due to the grid frequency being too high."""
 
     GRID_UNDERFREQUENCY = 33
-    """The grid frequency is under the minimum rated value."""
+    """The component is inoperable due to the grid frequency being too low."""
 
     GRID_DISCONNECTED = 34
-    """The grid is disconnected."""
+    """The component is inoperable due to the grid being disconnected.
+
+    This happens despite the AC relay being closed.
+    """
 
     GRID_VOLTAGE_IMBALANCE = 35
-    """Voltage imbalance between grid phases."""
+    """The component is inoperable due to the grid voltage being imbalanced.
+
+    This happens when the voltage of one or more phases is outside the
+    acceptable range.
+    """
 
     GRID_ABNORMAL = 36
-    """The grid is in an abnormal condition not covered by other grid-specific diagnostic codes."""
+    """The component is inoperable due to the grid being in a non-standard configuration."""
 
     EV_UNEXPECTED_PILOT_FAILURE = 40
     """Unexpected pilot failure in an electric vehicle (EV) component."""
@@ -155,7 +165,7 @@ class ElectricalComponentDiagnosticCode(enum.Enum):
     """Battery calibration is needed."""
 
     RELAY_CYCLE_LIMIT_REACHED = 60
-    """The relays have been cycled for the maximum number of times."""
+    """The battery's DC contactor or relays have reached end of life."""
 
     PV_REVERSAL_POLARITY = 70
     """Reverse polarity condition detected on the photovoltaic (PV) side."""
@@ -173,7 +183,7 @@ class ElectricalComponentDiagnosticCode(enum.Enum):
     """Ground fault detected on the photovoltaic (PV) side."""
 
     INVERTER_DC_UNDERVOLTAGE = 80
-    """The inverter DC bus voltage is under the minimum rated value."""
+    """The inverter is inoperable due to the DC voltage being too low."""
 
     INVERTER_DC_OVERVOLTAGE = 81
-    """The inverter DC bus voltage is over the maximum rated value."""
+    """The inverter is inoperable due to the DC voltage being too high."""

src/frequenz/client/common/microgrid/electrical_components/_state_code.py

@@ -21,7 +21,7 @@ class ElectricalComponentStateCode(enum.Enum):
     """
 
     UNAVAILABLE = 2
-    """The component is not available for use."""
+    """The component is temporarily unavailable for operation."""
 
     SWITCHING_OFF = 3
     """The component is in the process of switching off."""