Document internal representation of Quantity objects as floats

Closes #531

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

src/frequenz/sdk/timeseries/_quantities.py

@@ -393,7 +393,16 @@ class Power(
         6: "MW",
     },
 ):
-    """A power quantity."""
+    """A power quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_watts(cls, watts: float) -> Self:
@@ -557,7 +566,16 @@ class Current(
         0: "A",
     },
 ):
-    """A current quantity."""
+    """A current quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_amperes(cls, amperes: float) -> Self:
@@ -644,7 +662,16 @@ class Voltage(
     metaclass=_NoDefaultConstructible,
     exponent_unit_map={0: "V", -3: "mV", 3: "kV"},
 ):
-    """A voltage quantity."""
+    """A voltage quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_volts(cls, volts: float) -> Self:
@@ -757,7 +784,16 @@ class Energy(
         6: "MWh",
     },
 ):
-    """An energy quantity."""
+    """An energy quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_watt_hours(cls, watt_hours: float) -> Self:
@@ -867,7 +903,16 @@ class Frequency(
     metaclass=_NoDefaultConstructible,
     exponent_unit_map={0: "Hz", 3: "kHz", 6: "MHz", 9: "GHz"},
 ):
-    """A frequency quantity."""
+    """A frequency quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_hertz(cls, hertz: float) -> Self:
@@ -971,7 +1016,16 @@ class Percentage(
     metaclass=_NoDefaultConstructible,
     exponent_unit_map={0: "%"},
 ):
-    """A percentage quantity."""
+    """A percentage quantity.
+
+    Objects of this type are wrappers around `float` values.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
 
     @classmethod
     def from_percent(cls, percent: float) -> Self: