Fix and improve project docstrings

mkdocs.yml

@@ -112,6 +112,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
+            relative_crossrefs: true
           inventories:
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

pyproject.toml

@@ -124,6 +124,10 @@ check-yield-types = false
 arg-type-hints-in-docstring = false
 arg-type-hints-in-signature = true
 allow-init-docstring = true
+check-class-attributes = true
+check-style-mismatch = true
+require-inline-class-var-docs = true
+skip-checking-short-docstrings = true
 
 [tool.pylint.similarities]
 ignore-comments = ['yes']

src/frequenz/core/enum.py

@@ -76,11 +76,13 @@ class DeprecatingEnumType(enum.EnumType):
 
     Tip:
         Normally it is not necessary to use this class directly, use
-        [`Enum`][frequenz.core.enum.Enum] instead.
+        [`Enum`][..Enum] instead.
 
     Behavior:
 
     - In the class body, members may be declared as `NAME = DeprecatedMember(value, msg)`.
+      See [`DeprecatedMember`][..DeprecatedMember] and
+      [`deprecated_member()`][..deprecated_member] for details.
     - During class creation, these wrappers are replaced with `value` so that
       a normal enum member or alias is created by [`EnumType`][enum.EnumType].
     - The deprecated names are recorded so that:
@@ -98,7 +100,7 @@ def __new__(  # pylint: disable=too-many-locals
         classdict: Mapping[str, Any],
         **kw: Any,
     ) -> type[EnumT]:
-        """Create the new enum class, rewriting `DeprecatedMember` instances."""
+        """Create the new enum class rewriting [`DeprecatedMember`][...DeprecatedMember] members."""
         deprecated_names: dict[str, str] = {}
         prepared = super().__prepare__(name, bases, **kw)
 

src/frequenz/core/id.py

@@ -20,7 +20,7 @@
 
 Note:
     The `str_prefix` must be unique across all ID types. If you try to use a
-    prefix that is already registered, a `ValueError` will be raised when defining
+    prefix that is already registered, a warning will be logged when defining
     the class.
 
 To encourage consistency, the class name must end with the suffix "Id" (e.g.,
@@ -156,6 +156,13 @@ def __eq__(self, other: object) -> bool:
 
         Equality is defined as being of the exact same type and having the same
         underlying ID.
+
+        Args:
+            other: The object to compare against.
+
+        Returns:
+            True if `other` is of the same type and has the same underlying ID,
+            `NotImplemented` if `other` is of a different type.
         """
         # pylint thinks this is not an unidiomatic typecheck, but in this case
         # it is not. isinstance() returns True for subclasses, which is not
@@ -172,6 +179,13 @@ def __lt__(self, other: object) -> bool:
         """Check if this instance is less than another object.
 
         Comparison is only defined between instances of the exact same type.
+
+        Args:
+            other: The object to compare against.
+
+        Returns:
+            True if this instance is less than `other`, `NotImplemented` if
+            `other` is of a different type.
         """
         # pylint: disable-next=unidiomatic-typecheck
         if type(other) is not type(self):
@@ -184,6 +198,9 @@ def __hash__(self) -> int:
 
         The hash is based on the exact type and the underlying ID to ensure
         that IDs of different types but with the same numeric value have different hashes.
+
+        Returns:
+            The hash of this instance.
         """
         return hash((type(self), self._id))
 

src/frequenz/core/math.py

@@ -44,13 +44,14 @@ def __lt__(self, other: Self, /) -> bool:
 class Interval(Generic[LessThanComparableOrNoneT]):
     """An interval to test if a value is within its limits.
 
-    The `start` and `end` are inclusive, meaning that the `start` and `end` limites are
-    included in the range when checking if a value is contained by the interval.
+    The [`.start`][.start] and [`.end`][.end] are inclusive, meaning that the
+    [`.start`][.start] and [`.end`][.end] limits are included in the range when
+    checking if a value is contained by the interval.
 
-    If the `start` or `end` is `None`, it means that the interval is unbounded in that
-    direction.
+    If the [`.start`][.start] or [`.end`][.end] is `None`, it means that the interval
+    is unbounded in that direction.
 
-    If `start` is bigger than `end`, a `ValueError` is raised.
+    If [`.start`][.start] is bigger than [`.end`][.end], a `ValueError` is raised.
 
     The type stored in the interval must be comparable, meaning that it must implement
     the `__lt__` method to be able to compare values.
@@ -74,14 +75,13 @@ def __post_init__(self) -> None:
             )
 
     def __contains__(self, item: LessThanComparableOrNoneT) -> bool:
-        """
-        Check if the value is within the range of the container.
+        """Check if the value is within the range of the container.
 
         Args:
             item: The value to check.
 
         Returns:
-            bool: True if value is within the range, otherwise False.
+            True if value is within the range, otherwise False.
         """
         if item is None:
             return False

src/frequenz/core/typing.py

@@ -207,7 +207,7 @@ def new(cls, value: int = 1) -> Self:
         class NoInitConstructibleABCMeta(ABCMeta, NoInitConstructibleMeta):
             pass
 
-        class MyAbstractClass(metaclas=NoInitConstructibleABCMeta):
+        class MyAbstractClass(metaclass=NoInitConstructibleABCMeta):
             @abstractmethod
             def do_something(self) -> None:
                 ...