Skip to content

docs: a doc comment whose first line has a colon renders its prose as a Type field #2745

Closed

Description

@JarryShaw

Describe the bug
When an attribute doc comment (#:) has a colon on its first line, Napoleon parses that line as "type: description". The text before the colon goes into a Type field and drops out of the prose. Usually there is no warning, so nothing catches it. #2744 fixed the two cases that did warn: IGMPv3 Query.checksum and the DTLS reassembler's __protocol_type__.

Reproduction
Build docs/ at ab7be2fb0 in a clean venv. In the generated page for pcapkit.protocols.data.internet.igmp, the group attribute shows Type: Group address and its description starts after the colon. Other first lines with the same shape, found by the #2744 review (some may be false positives):

  • Group address: in protocols/data/internet/igmp.py and igmpv3.py.
  • Extension data: in protocols/data/application/tls.py.
  • Unified-header first octet: in protocols/schema/application/dtls.py.
  • First length octet: in protocols/schema/internet/mh.py.
  • Protocol Type: in the GRE schema and data modules.
  • Similar comments in hopopt, ipv6_opts, ipv4, tcp, raw, dccp and radiotap, in the traceflow and reassembly data modules, and in corekit/checksum/internet.py.
  • The "What __proto__ is keyed by" comments on the Frame, Link, Internet, PCAPNG and pcap Frame classes.

Also, in #2744 the netlink footnote marker leaks framing* into that page's og:description and meta description.

Expected behavior
Every #: comment renders as prose with no stray Type field, and a project test fails on any new first-line colon that Napoleon would misread.

System information
Linux, CPython 3.15.2, Sphinx 9.2.0, sphinx-autodoc-typehints 3.17.2/3.17.4, checkout ab7be2fb0.

Activity

  1. added
    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)
    docsPull requests that change documentation only (docs: subject prefix)
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 3, 2026
  2. added this to the PyPCAPKit v1.6 milestone on Nov 3, 2026
  3. JarryShaw commented on Nov 3, 2026

    @JarryShaw
    OwnerAuthor

    A fix is in progress on a branch off ab7be2fb0. It finds the affected comments from the built docs, separates out false positives, rewords the real cases the way #2744 did, and adds a guard test under tests/project/. The netlink meta-description item is being folded into #2744 instead.

  4. JarryShaw commented on Nov 3, 2026

    @JarryShaw
    OwnerAuthor

    The PR is #2746.

  5. removed
    wipWork in flight - a covering PR is open or an agent is actively on it
    on Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugIssues reporting a defect (set by the bug report template; a default, not an assessment)docsPull requests that change documentation only (docs: subject prefix)

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions