docs: Fix and improve docstrings#150
Merged
Merged
Conversation
github-actions
Bot
added
part:tooling
llucax
force-pushed
the
fix-docstrings
branch
2 times, most recently
from
9c91c57 to
10ee0df
Compare
llucax
added
the
cmd:skip-release-notes
Add the `relative_crossrefs: true` option to the mkdocstrings Python handler options in mkdocs.yml. This enables relative cross- reference resolution in docstrings, which is the current convention being rolled out across all Frequenz Python projects. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Add missing pydoclint options to the [tool.flake8] configuration: - check-class-attributes = true: enforce documentation of class attributes - check-style-mismatch = true: detect when docstrings use a different style than what is configured - require-inline-class-var-docs = true: require inline documentation for class variables These are part of the convention being actively rolled out across all Frequenz Python projects. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
- Fix subject-verb agreement in __init__.py module docstring: 'provide' -> 'provides' - Fix article agreement in ApparentPower class docstring: 'A apparent power' -> 'An apparent power' - Fix typo 'the a current' -> 'a current' in ApparentPower, Power and ReactivePower __truediv__ overload docstrings Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Properties must use a one-line noun phrase starting with 'The' rather than imperative style with a Returns: section. - base_value: 'Return the value...' + Returns section -> 'The value of this quantity in the base unit.' - base_unit: 'Return the base unit...' + Returns section -> 'The base unit of this quantity, or None if this quantity has no unit.' Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Several operator docstrings were copied from Power and never updated to refer to the correct quantity type: - ApparentPower.__mul__: was 'power or energy' (wrong, no Energy return), now 'Scale this apparent power by a scalar or percentage' - ApparentPower.__truediv__: 'this power' -> 'this apparent power' throughout all overloads and implementation - Energy.__mul__: was 'percentage' only, now 'scalar or percentage' to match the float | Percentage signature - Energy.__truediv__: implementation was 'power or duration' (omitted the Self and float cases), now 'scaled energy, ratio, power, or duration' - ReactivePower.__mul__: was 'power or energy' (wrong), now 'Scale this reactive power by a scalar or percentage' - ReactivePower.__truediv__: 'this power' -> 'this reactive power' throughout all overloads and implementation Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
- Remove trailing blank line inside from_string() Raises: section - Fix __truediv__ overload 1: arg description incorrectly mentioned 'or percentage' in a float-only overload - Capitalize arg descriptions in NoDefaultConstructible.__call__: 'ignored positional arguments' -> 'Ignored positional arguments' Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
…_.py Use name-based auto-resolve form [`Foo`][] and relative cross- references like [.Power.from_watts] and [.experimental.marshmallow] instead of absolute fully-qualified paths like [frequenz.quantities.Power]. This is consistent with the convention of using relative cross-references (relative_crossrefs: true) wherever possible. Also add backtick formatting to cross-reference display text for the class list and the Quantity mention in the prose. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
The experimental marshmallow module references marshmallow.ValidationError in docstrings. Add the marshmallow readthedocs inventory so mkdocstrings can resolve the cross-reference correctly. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
- Module docstring: absolute cross-ref -> [`QuantitySchema`][]
- serialize_as_string_default: fix summary ('The context variable...'),
backtick True/False
- _QuantityField class: add 'A' prefix, add cross-refs for Quantity,
field_type, QuantitySchema.TYPE_MAPPING, QUANTITY_FIELD_CLASSES;
use relative references (.field_type, ..QuantitySchema.TYPE_MAPPING)
- field_type attribute: add Quantity cross-reference
- _serialize: add Args and Returns sections
- _deserialize: add Args, Returns, and Raises sections with
marshmallow.ValidationError cross-reference
- Field subclasses (9): add 'A' prefix and quantity cross-refs
- QUANTITY_FIELD_CLASSES: fix summary ('The mapping from...'),
add cross-ref to QuantitySchema.TYPE_MAPPING
- QuantitySchema: 'Example usage:' -> 'Example:'
- TYPE_MAPPING: add missing inline docstring
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
…aths mkdocstrings resolves targets not starting with '.' as absolute paths, and name-based lookup (empty []) is unreliable in module/attribute docstring contexts. Fix all ambiguous references: - __init__.py: use [.ClassName] (relative to module) for all type cross-refs in the module docstring instead of [`Foo`][] - marshmallow.py module docstring: [.QuantitySchema] instead of [] - _QuantityField: use frequenz.quantities.Quantity absolute path for Quantity (external module); use [..QuantitySchema] (two dots = module level from class context) for QuantitySchema; use [..X] for all module-level symbols referenced from a class docstring - QUANTITY_FIELD_CLASSES: use [..QuantitySchema.TYPE_MAPPING] (constant docstring context: one dot = constant itself, two dots = module) - Field subclasses: use frequenz.quantities.X absolute paths for all quantity type cross-references (they live in a different module) Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
- Wrap overlong lines (E501) in class summary, _serialize and _deserialize summaries, and QUANTITY_FIELD_CLASSES docstring - _serialize: add missing Raises section for TypeError (DOC501/DOC503) - _deserialize: document both TypeError and ValidationError in Raises; use bare exception name 'ValidationError' for pydoclint compatibility (DOC503 cannot match cross-reference markup in exception names), with a link to marshmallow.ValidationError in the description - QuantitySchema: remove blank line between Example: header and code fence (D412) - _deserialize summary: rewrite as single line ending with period to fix D205 and D400 Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
All cross-references to frequenz.quantities.* symbols were written as absolute paths. Replace them with dot-notation relative references: - Depth-1 objects (classes, module-level constants): use ....X (3 levels up from class/constant → frequenz.quantities.X) - Depth-2 objects (methods, class attributes): use .....X (4 levels up) - In _serialize/_deserialize method docstrings: [.field_type] was wrong (resolved to the method's own field_type, which doesn't exist); fixed to [..field_type] (1 level up → _QuantityField.field_type) Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Marenz
approved these changes
Jun 30, 2026
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
2 participants
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.
🤖 This pull request is part of an automated effort to improve the docstring documentation of all our projects.
Main issues being resolved:
base_valueandbase_unitin_quantity.pyused imperative style with aReturns:section; corrected to one-line noun-phrase style (convention for properties)ApparentPower.__mul__andReactivePower.__mul__were copied fromPower.__mul__and incorrectly mentioned an 'energy' return and 'duration' argument that don't apply;Energy.__mul__omitted thefloatcase;__truediv__implementation docstrings inApparentPowerandReactivePowerreferred to 'this power' throughout instead of the actual type_quantity.pyissues: trailing blank line infrom_string()Raises section;__truediv__overload 1 incorrectly mentioned 'or percentage' in afloat-only overload; arg descriptions inNoDefaultConstructible.__call__started with lowercase__init__.pymodule docstring used fully-qualified[Name][frequenz.quantities.Name]forms; replaced with relative[Name][.Name]refs and backtick-styled display textexperimental/marshmallow.py: missing 'A' prefix on class summaries, symbol mentions without cross-references throughout,_serialize/_deserializemissingArgs:/Returns:/Raises:sections, unsupportedExample usage:admonition renamed toExample:, missing inline docstring forTYPE_MAPPINGclass variablerelative_crossrefs: trueto mkdocstrings options; addedcheck-class-attributes,check-style-mismatch, andrequire-inline-class-var-docsto pydoclint config; added marshmallowobjects.invinventory for cross-reference resolution