Closed
docs: fix docstring config and sweep DOC503 violations#9
Conversation
Add missing mkdocstrings options to mkdocs.yml: - `relative_crossrefs: true` (convention roll-out) - `show_symbol_type_toc: true` Add missing pydoclint options to pyproject.toml [tool.flake8]: - `check-class-attributes = true` - `check-style-mismatch = true` (convention roll-out) - `require-inline-class-var-docs = true` (convention roll-out) - `skip-checking-short-docstrings = true` Options are ordered alphabetically within each block. Signed-off-by: Copilot <copilot@github.com>
Remove extraneous exceptions from Raises sections where only the subclass is directly raised (ReceiverError when only ReceiverStoppedError is raised): - _anycast.py: Receiver.consume - _bidirectional.py: Handle.consume - util/_merge.py: Merge.consume - util/_merge_named.py: MergeNamed.consume Add # noqa: DOC503 where exceptions are raised indirectly (e.g., via asyncio.get_running_loop() or qualified-name import mismatch): - _base_classes.py: Receiver.__anext__, Receiver.receive - util/_event.py: Event.consume - util/_select.py: Selected.value, select() - util/_timer.py: Timer.__init__, Timer.reset Also fix misleading Raises description in Receiver.receive: the ReceiverStoppedError description was "if there is some problem with the receiver" (should be "if the receiver stopped producing messages"). Signed-off-by: Copilot <copilot@github.com>
Simplify property docstrings to the conventional one-liner noun-phrase
format (removing redundant Returns: sections that repeat the summary):
- _bidirectional.py: Bidirectional.client_handle, service_handle
- util/_event.py: Event.name, is_set, is_stopped
- util/_timer.py: SkipMissedAndDrift.delay_tolerance, Timer.interval,
missed_tick_policy, loop, is_running
Simplify no-arg methods that only return/print self to one-liner
imperative format (removing redundant Returns: sections):
- _base_classes.py: Receiver.__aiter__
- util/_event.py: Event.__str__, __repr__
- util/_select.py: Selected.__str__, __repr__
- util/_timer.py: MissedTickPolicy.__repr__, SkipMissedAndDrift.__str__,
__repr__, Timer._now, __str__, __repr__
Fix wrong class name in Error.__init__ docstring ("Create a ChannelError
instance" -> "Create an instance").
Add cross-references to Bidirectional.client_handle and service_handle.
Signed-off-by: Copilot <copilot@github.com>
Copilot
AI
changed the title
docs: fix and improve project docstrings configuration and violations
docs: fix docstring config and sweep DOC503 violations
Jun 30, 2026
Copilot created this pull request from a session on behalf of
llucax
June 30, 2026 07:32
View session
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Aligns
mkdocs.ymlandpyproject.tomlwith the Frequenz Python docstring conventions, then fixes all pydoclint violations surfaced by the updated config.Config (
mkdocs.yml)relative_crossrefs: true(convention roll-out) andshow_symbol_type_toc: trueConfig (
pyproject.toml—[tool.flake8]pydoclint options)Added missing keys (alphabetically ordered):
check-class-attributes = truecheck-style-mismatch = true(convention roll-out)require-inline-class-var-docs = true(convention roll-out)skip-checking-short-docstrings = trueDOC503 fixes — 11 violations
Removed incorrect parent-class exceptions (subclass is what's actually raised):
_anycast.py,_merge.py,_merge_named.py: removedReceiverErrorfromRaises:(onlyReceiverStoppedErrorraised directly)_bidirectional.py: removedReceiverStoppedErrorfromRaises:(onlyReceiverErrorraised directly)Added
# noqa: DOC503where exceptions are raised indirectly (same pattern as existingDOC502suppressions):_base_classes.pyReceiver.__anext__/receive—ReceiverErrorpropagates from inner callsutil/_event.pyEvent.consume— pydoclint qualified-name mismatch (_exceptions.ReceiverStoppedError)util/_select.pySelected.value/select()— stored exception and indirect raise via_stop_pending_tasks()util/_timer.pyTimer.__init__/reset—RuntimeErrorfromasyncio.get_running_loop()Docstring text fixes
Error.__init__: summary said "Create a ChannelError instance" (wrong class)Receiver.receive:ReceiverStoppedErrordescription said "if there is some problem" instead of "if the receiver stopped producing messages"Style improvements
Per convention (properties → one-liner noun phrase; zero-arg return methods → one-liner imperative), removed redundant
Returns:sections from properties and__str__/__repr__methods across_bidirectional.py,_event.py,_select.py, and_timer.py.