Problem
src/pythonnative/mutations.py defines five frozen dataclasses that make up the mutation protocol. CreateOp (lines 44-57) documents its fields with a Google-style Attributes: section:
@dataclass(frozen=True)
class CreateOp:
"""Create a native view for ``tag`` of element type ``type_name``.
Attributes:
tag: Unique integer identity assigned by the reconciler.
type_name: Element type name (e.g. ``"Text"``).
props: Initial *clean* props; ...
"""
The other four don't. UpdateOp (lines 61-70), InsertOp (lines 73-85), DestroyOp (lines 88-97), and SetFrameOp (lines 100-117) each have a summary and a prose paragraph but no Attributes: block, so tag, changed_props, parent_tag, child_tag, index, x, y, width, and height are undocumented.
This shows up on the published API page: docs/api/mutations.md renders the module with mkdocstrings, so CreateOp gets a formatted attributes table and its siblings don't. It's also inconsistent with the Google docstring convention that CONTRIBUTING.md asks for in src/pythonnative/.
Suggested fix
- Add an Attributes: section to UpdateOp, InsertOp, DestroyOp, and SetFrameOp, matching the style of CreateOp. The existing prose already contains most of the information; for example, UpdateOp.changed_props should note that a removed prop appears with a value of None, and InsertOp.index should note that handlers clamp it to the current child count.
- Keep the existing summary lines and paragraphs; only add the sections.
- No code or test changes needed.
See the documentation style guide for docstring examples.
Verification
- uv run ruff check . passes (the D rules are enabled for src/pythonnative/).
- uv run --group docs mkdocs build --strict passes, and the Mutation ops page (uv run --group docs mkdocs serve) shows an attributes table for all five ops.
Suggested commit message
docs(mutations): add Attributes sections to the remaining op docstrings
Problem
src/pythonnative/mutations.py defines five frozen dataclasses that make up the mutation protocol. CreateOp (lines 44-57) documents its fields with a Google-style Attributes: section:
The other four don't. UpdateOp (lines 61-70), InsertOp (lines 73-85), DestroyOp (lines 88-97), and SetFrameOp (lines 100-117) each have a summary and a prose paragraph but no Attributes: block, so tag, changed_props, parent_tag, child_tag, index, x, y, width, and height are undocumented.
This shows up on the published API page: docs/api/mutations.md renders the module with mkdocstrings, so CreateOp gets a formatted attributes table and its siblings don't. It's also inconsistent with the Google docstring convention that CONTRIBUTING.md asks for in src/pythonnative/.
Suggested fix
See the documentation style guide for docstring examples.
Verification
Suggested commit message