Skip to content

Fix and improve docstring documentation#279

Merged
llucax merged 14 commits into
frequenz-floss:v1.x.xfrom
llucax:fix-docstrings
Jun 30, 2026
Merged

Fix and improve docstring documentation#279
llucax merged 14 commits into
frequenz-floss:v1.x.xfrom
llucax:fix-docstrings

Conversation

@llucax

@llucax llucax commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

🤖 This pull request is part of an automated effort to improve the docstring documentation of all our projects.

Main issues being resolved:

  • Typos: "highlevel" → "high-level" throughout
  • Class docstring summaries missing required "A"/"An" article
  • Boolean method summaries using "Check if ..." instead of "Return whether ..."
  • Property docstrings using imperative mood instead of noun phrases
  • Missing `Args:`, `Returns:`, and `Yields:` sections in several methods
  • Missing inline attribute docstrings on `QueueItem` dataclass fields
  • Bare backtick symbol mentions that should be cross-reference links
  • Absolute cross-references replaced with relative ones where applicable
  • Types appearing inside docstring sections (Yields: datetime:)
  • Spurious `Returns:` section on a generator method (`missed_runs`)
  • Redundant sentence repeating the summary in `missed_runs`
  • Non-standard `Deprecation:` admonition replaced with `Warning:`
  • Missing imports and `await` in fenced code examples
  • Deprecated `.components` usage replaced with `.target` in example
  • Factually incorrect module docstring in `conftest.py` (claimed pylint, is Sybil)
  • Stale comment describing `QueueItem` as a tuple (it is a dataclass)

Other things to note:

  • The `relative_crossrefs: true` mkdocstrings option was added to `mkdocs.yml` as part of the rolling-out of relative cross-reference conventions.
  • Three new pydoclint options were added to `pyproject.toml` (`check-class-attributes`, `check-style-mismatch`, `require-inline-class-var-docs`) as part of the rolling-out of stricter docstring checks.
  • The `ActorDispatcher` example code block was re-indented to sit properly inside the `Example:` admonition, which also required adding missing imports (`Any`, `Self`) and an `await` on `new_running_state_event_receiver`.

@llucax llucax requested a review from a team as a code owner June 30, 2026 12:14
@llucax llucax requested review from stefan-brus-frequenz and removed request for a team June 30, 2026 12:14
@github-actions github-actions Bot added part:docs Affects the documentation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) part:dispatcher Affects the high-level dispatcher interface labels Jun 30, 2026
llucax added 2 commits June 30, 2026 14:18
@llucax
Enable relative cross-references in mkdocstrings
eaf7143 
Add relative_crossrefs: true to the mkdocstrings Python handler
options in mkdocs.yml. This is part of the rolling-out of the
relative cross-reference convention across all Frequenz projects.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Enable stricter pydoclint checks for class attributes
c9f3352 
Add check-class-attributes, check-style-mismatch, and
require-inline-class-var-docs to the pydoclint configuration in
pyproject.toml. These are part of the rolling-out of stricter
docstring conventions across all Frequenz projects.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
llucax added 9 commits June 30, 2026 14:19
@llucax
Fix DispatchEvent alias docstring style
8da3da3 
The module-level type alias docstring must use the attribute convention:
a noun phrase starting with "The".

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in _dispatch.py
1c26393 
- Add missing "A" article to class summary (Dispatch)
- Fix property summary style: use noun phrase instead of imperative
  (started property: "Whether the dispatch is currently started.")
- Fix boolean method summary: use "Return whether ..." instead of
  "Check if ..." (started_at)
- Fix Args description: add "The" prefix and missing period
- Fix Yields type annotation (remove type from docstring section)
- Remove wrong Returns: section from generator method (missed_runs)
- Remove redundant sentence that repeats the summary
- Drop the # noqa: DOC405 suppression that is no longer needed

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in _merge_strategies.py
df24fa3 
- Add missing "A" article to class summaries (MergeByType, MergeByTypeTarget)
- Fix method summary mood: use imperative "Return whether ..." instead
  of noun phrases for identity and filter methods
- Add missing Args: and Returns: sections to all abstract method overrides
- Expand filter docstring with the actual propagation logic

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in _bg_service.py
df5ba20 
- Add missing "A" articles to MergeStrategy and DispatchScheduler summaries
- Fix MergeStrategy.identity: add proper summary with Args and Returns
- Add inline docstrings to all QueueItem dataclass fields (time,
  priority, dispatch_id, dispatch), fixing missing attribute documentation
- Add Args section to QueueItem.__init__
- Fix stale comment: _scheduled_events used tuples (now uses QueueItem)
- Add missing periods to bullet point list entries in
  new_running_state_event_receiver docstring
- Replace bare backtick symbol mentions with proper cross-references
  (MergeByType, MergeByTypeTarget, MergeStrategy, identity, filter)
- Fix tense mismatch in _execute_scheduled_event summary
  ("schedules" → "schedule")
- Add missing Args section to _fetch
- Fix _update_changed_running_state: use "Return whether ..." mood
- Add missing periods to Args descriptions in _update_changed_running_state

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in _actor_dispatcher.py
6509508 
- Add missing "A"/"An" articles to class summaries (DispatchActorId,
  DispatchInfo, ActorDispatcher, ActorAndChannel)
- Fix components property: use noun phrase ("The target components
  (deprecated)") and replace non-standard Deprecation: admonition
  with Warning:
- Fix cross-reference to target attribute: use relative ref [.target]
  instead of absolute
- Add "The" prefix to target and options attribute docstrings
- Fix DispatchInfo.__init__ Args: add "The" to descriptions
- Replace "Example usage:" with standard "Example:" admonition
- Fix indentation of the entire example code block
- Add missing imports in example code (Any, Self from typing)
- Replace deprecated .components usage with .target in example
- Add missing await to new_running_state_event_receiver call in example
- Add missing Args section to _start_actor
- Fix misleading _stop_actor summary: it stops one actor, not all

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in __init__.py
8a116c6 
- Fix typo: "highlevel" → "high-level"
- Add backticks to all cross-reference display text so rendered links
  read as code (Dispatcher, Dispatch, ActorDispatcher, Created,
  Updated, Deleted)

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix docstring violations in _dispatcher.py
5c9db97 
- Fix typo: "highlevel" → "high-level" in module docstring and class
  docstring
- Fix cross-references: use relative refs [.new_lifecycle_events_receiver]
  and [.new_running_state_event_receiver] in class docstring
- Fix example imports: add missing Receiver, DispatchInfo, Actor
- Fix example whitespace: remove double space (key  = → key =)
- Fix example bugs: add missing await to start_managing and
  new_running_state_event_receiver calls
- Add "A" article to class summary
- Fix microgrid_id Args description: "id" → "ID"
- Fix sign_secret Args description: add period and restructure
- Fix Raises description: add missing period
- Add missing Args section to cancel method
- Fix is_managed summary: use "Return whether ..." for boolean methods
- Replace bare backtick mentions with cross-references (Dispatcher,
  start_managing, stop_managing)
- Add missing period after stop_managing reference
- Fix retry_interval description: "Retry interval" → "The retry
  interval to use ..."
- Fix client property: use noun phrase with cross-reference to
  DispatchApiClient
- Fix new_lifecycle_events_receiver: improve summary and Returns desc
- Fix new_running_state_event_receiver: improve summary, add missing
  period to MergeStrategy sentence, fix bullet list periods, fix
  merge_strategy Args description

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Add release notes for docstring improvements
64d6694 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix unresolved cross-reference warnings in mkdocs build
cc82ed5 
- Fix relative ref [.target] → [..target] in DispatchInfo.components:
  target is a sibling of components, not a child
- Remove DispatchApiClient cross-reference: the symbol does not appear
  in the client-dispatch inventory; use plain prose description
- Fix [Dispatcher][] → [frequenz.dispatch.Dispatcher]: bare name is
  not resolvable without the full qualified path
- Fix [.start_managing] and [.stop_managing] → [..start_managing] and
  [..stop_managing]: these are siblings of start_managing within
  Dispatcher, not children

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
llucax added 3 commits June 30, 2026 14:22
@llucax
Fix unused Self import in example code (pylint violation)
de6d749 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix flake8 violations
233715d 
- Remove "(deprecated)" suffix from components property one-liner to
  avoid D402 (pydocstyle: first line should not be function's signature)
- Wrap long line in start_managing docstring (E501: > 100 chars)

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Convert absolute cross-references to relative
0424d98 
- __init__.py (module frequenz.dispatch): use .X for children
  (.Dispatcher, .Dispatch, .ActorDispatcher, .Created, .Updated,
  .Deleted)
- _bg_service.py (DispatchScheduler.new_running_state_event_receiver):
  use ....X for frequenz.dispatch.* (4 levels: method → class →
  private module → package)
- _dispatcher.py (Dispatcher.start_managing and
  new_running_state_event_receiver): use ...X for frequenz.dispatch.*
  (3 levels: method → class → package, since Dispatcher is exported
  directly under frequenz.dispatch)

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax llucax enabled auto-merge June 30, 2026 12:50
@llucax llucax requested a review from Marenz June 30, 2026 12:50
@llucax llucax added this pull request to the merge queue Jun 30, 2026
Merged via the queue into frequenz-floss:v1.x.x with commit 1374b39 Jun 30, 2026
8 checks passed
@llucax llucax deleted the fix-docstrings branch June 30, 2026 13:15
@Marenz

Marenz commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Manually reviewed!!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Marenz Marenz Marenz approved these changes
@stefan-brus-frequenz stefan-brus-frequenz Awaiting requested review from stefan-brus-frequenz stefan-brus-frequenz is a code owner automatically assigned from frequenz-floss/api-dispatch-team

Assignees

No one assigned

Labels

part:dispatcher Affects the high-level dispatcher interface part:docs Affects the documentation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@llucax @Marenz