From ce06f4d98f7b60a1d0f2ec45adbf262efee916af Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:19:28 +0000
Subject: [PATCH 1/6] config: Add missing pydoclint options

Add missing pydoclint options to `[tool.flake8]` in `pyproject.toml`:
- `check-class-attributes = true`
- `check-style-mismatch = true`
- `require-inline-class-var-docs = true`
- `skip-checking-short-docstrings = true`

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 pyproject.toml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index 9bfb339..a1c1ac5 100644
--- a/pyproject.toml
+++ b/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']

From daa6908d70030c6d56659cb16f076bd6ae3d1ba1 Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Mon, 29 Jun 2026 15:32:06 +0200
Subject: [PATCH 2/6] config: Add missing mkdocs option

Add `relative_crossrefs: true` to `mkdocs.yml` `mkdocstrings` options.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index 40c356c..d839d3d 100644
--- a/mkdocs.yml
+++ b/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

From 0052c139ed22f4a31c0222437c7ae548c3d4b04d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:20:34 +0000
Subject: [PATCH 3/6] docs: Fix docstring violations in `math`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `Interval` class: fix typo "limites" → "limits", add cross-references
  for `.start` and `.end` attributes in the class body docstring
- `Interval.__contains__`: move summary to the opening line, remove type
  hint from the `Returns:` section (DOC111 equivalent)

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 src/frequenz/core/math.py | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/frequenz/core/math.py b/src/frequenz/core/math.py
index 290b898..2fca7a9 100644
--- a/src/frequenz/core/math.py
+++ b/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

From 2523d4c21ae66a317c4fedbe2aed2390309b2303 Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Mon, 29 Jun 2026 15:33:25 +0200
Subject: [PATCH 4/6] docs: Fix docstring violations in `id`

- Module docstring: correct the `Note:` admonition that incorrectly
  stated a `ValueError` would be raised for duplicate `str_prefix`
  registrations; the code only logs a warning
- `BaseId.__eq__`, `__lt__`: add missing `Args:` and `Returns:` sections
- `BaseId.__hash__`: add missing `Returns:` section

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 src/frequenz/core/id.py | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/frequenz/core/id.py b/src/frequenz/core/id.py
index 1abb1b7..fffa9a4 100644
--- a/src/frequenz/core/id.py
+++ b/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))
 

From 37af38a0bc13e43c8be270d790d64747b5112ff0 Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Mon, 29 Jun 2026 15:34:12 +0200
Subject: [PATCH 5/6] docs: Fix docstring violations in `enum`

- `DeprecatingEnumType.__new__`: add cross-reference for
  `DeprecatedMember`
- `DeprecatingEnumType` class docstring: add cross-references for
  `DeprecatedMember` and `deprecated_member()` in the Behavior block

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 src/frequenz/core/enum.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/frequenz/core/enum.py b/src/frequenz/core/enum.py
index 76a9094..d5edd2b 100644
--- a/src/frequenz/core/enum.py
+++ b/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)
 

From 7f9e2f5702ac7c3530d37e156114a83565f8d78b Mon Sep 17 00:00:00 2001
From: Leandro Lucarella <luca-frequenz@llucax.com>
Date: Mon, 29 Jun 2026 15:34:56 +0200
Subject: [PATCH 6/6] docs: Fix docstring violations in `typing`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fix typo `metaclas` → `metaclass` in `NoInitConstructibleMeta`
docstring example.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
---
 src/frequenz/core/typing.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/frequenz/core/typing.py b/src/frequenz/core/typing.py
index efc6b76..fabc68a 100644
--- a/src/frequenz/core/typing.py
+++ b/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:
                 ...