FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add `Attributes:` sections to the `UpdateOp`, `InsertOp`, `DestroyOp`, and `SetFrameOp` docstrings · Issue #61 · pythonnative/pythonnative · GitHub

Repository navigation

Add Attributes: sections to the UpdateOp, InsertOp, DestroyOp, and SetFrameOp docstrings #61

Description

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

Activity

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgood first issueGood for newcomers

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions


    Back | FazBrowse Home | New Git URL