Skip to content

docs: Document Attributes for NamedTuple, dataclass, and TypedDict fields #80

Description

@tony

autodoc renders every field of a NamedTuple, dataclass, or TypedDict whether or not the docstring describes it. An undocumented NamedTuple field reaches the API docs as "Alias for field number 0"; a dataclass or TypedDict field reaches it bare. AGENTS.md now requires an Attributes section covering every field, and this issue tracks the code that predates that rule.

1 class is missing an Attributes entry for 3 fields in total.

Rendered on the published site today

These modules are named by an autodoc directive under docs/, so the stubs are live in the API docs right now.

  • SetupDict (TypedDict) in linkify_issues — missing version, parallel_read_safe, parallel_write_safe

Fixing one

Add a NumPy-style Attributes section naming every field, with its type and what it holds:

class Example(t.NamedTuple):
    """One-line summary.

    Attributes
    ----------
    path : pathlib.Path | None
        What this field holds, and what ``None`` means.
    """

Partial coverage does not help: a class with three fields and two documented still ships a stub for the third.


Links are permalinks anchored to v0.0.19; a file that changed since the last release is linked at the current trunk commit instead. Produced by a static AST scan of the package for NamedTuple, dataclass, and TypedDict classes whose docstring omits a field, excluding tests and private classes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions