Repository navigation
docs: #719-style prose sweep after the #1090–#1102 defect wave #1103
Description
Is your feature request related to a problem? Please describe.
The defect wave #1090–#1102 changes code and docstrings in several modules, and #719's two rounds of prose sweeps predate those changes. The maintainer asked for another #719-style pass over the docs and comments once the wave lands.
Describe the solution you'd like
Re-read the prose that the wave's merged PRs touched or made stale: docstrings, comments, docs/ and pep.rst. Apply #719's rules: no churn, accuracy first, no timed context, and only prose changes, with an AST guard on every .py.
Blocked until
Every issue in #1090–#1102 is closed.
Describe alternatives you've considered
Folding the sweep into each fix PR was rejected: thirteen parallel PRs editing shared prose would conflict.
Activity
JarryShaw commentedon Oct 6, 2026
Add to this sweep:
ProtocolBase.pack()(protocol.py:559-576) rebuilds frommake(**kwargs)and ignores the instance's parsed or constructed state. A bareX(...).pack()therefore returns defaults. Neither the docstring nor the rst docs say so. This came up in the #1143 review.JarryShaw commentedon Oct 6, 2026
Add to this sweep, after #1147 merges:
docs/source/ext.rst:~266saysfrom_data"warnsUnknownFieldWarning" and that its keywords "come from your_make_data". Caller-supplied keywords now raiseUnsupportedCall._check_construction_keywordsdocstring describeskwargsas what remains after__init__.from_datacalls it as well now.JarryShaw commentedon Oct 6, 2026
Still blocked, with a new condition. Every issue in #1090–#1102 is closed, but the sweep is meant to run after all the defects the wave turned up are fixed, so that it reads the final docstrings once. It now unblocks when #1127, #1133, #1144, #1151, #1154, #1155 and #1156 are all closed.
JarryShaw commentedon Oct 7, 2026
Still blocked, with a new condition. All seven issues named in the last condition are now closed. Two more defects from the same audit are now being fixed, #1165 and #1167, and they edit
extraction.py,dumpkit/pcap.py,ipv4.pyandudp.py. The sweep unblocks once #1165 and #1167 are both closed, so it reads the final docstrings once.JarryShaw commentedon Oct 7, 2026
Condition extended: the #1169 cross-review turned up #1170, a defect in the same class that touches
ipv4.py,ipv6.py,udp.pyand the shared_import_next_layer. The sweep now unblocks once #1165, #1167 and #1170 are all closed.JarryShaw commentedon Oct 7, 2026
The previous condition is met: #1165, #1167 and #1170 are all closed. Two defects from the same audit are still in flight: #1172 (
l2tpv2.py) and #1173 (ipv6_route.py,mh.py,application.py). The sweep would read the docstrings of the files they edit, so it now unblocks when #1172 and #1173 are both closed. These are the last known items from this audit.JarryShaw commentedon Oct 7, 2026
Unblocked: #1172 and #1173 are both closed (#1174 and #1176 merged at 04:00Z and 04:01Z). Now
pending. Three later items are still open: #1175 (l2tpv2.py), #1177 (ipv6.py) and #1178 (ipv6_ext.py). The sweep skips those three files and they get a delta pass once each issue closes.JarryShaw commentedon Oct 7, 2026
Dispatched as three prose slices, each scoped to
git diff b10e7951b origin/main:protocols,schema-dataandfoundation-docs. The #1175/#1177/#1178 files are excluded.192 remaining items
docs(protocols,foundation,tests): state current behaviour in maker, r…
docs: #719-style prose sweep after the #1090-1102 defect wave (#2408)
JarryShaw commentedon Oct 28, 2026
PR #2415 (round 2 of this sweep) converted every
pcapkit.protocols.protocol.Protocol.<member>cross-reference underpcapkit/toProtocolBase.<member>, since that's the class that actually defines them —Protocolitself is just a docstring +__init_subclass__. It deliberately leftdocs/source/andtests/untouched (31 occurrences) because the conversion has a real rendering effect: in the built Sphinx docs, aProtocol.Xlink lands on the page's full member documentation, whileProtocolBase.Xlands on a docstring-less stub that links onward. The cross-review measured this directly — the conversion moves 63 rendered links from full entries to stubs (Protocol.<m>hrefs go from 154 to 91 in the built HTML), and_decode_next_layer's docs page shrinks from a 3.7 KB docstring to a 14 KB signature list.Decision needed: which direction is correct?
protocol.rstsoProtocolBasehosts the full member entries (matching where the members are actually defined), then finish convertingpcapkit/,docs/andtests/together — this is technically correct but is a real doc-architecture change, not a drop-in fix.pcapkit/conversion back toProtocol.X, since that's already where the full docs render, and leave the Sphinx rendering structure as-is.My recommendation (matching the cross-reviewer's): option 1.
ProtocolBaseis the real defining class, and restructuringprotocol.rstonce is cleaner than permanently pointing cross-references at the wrong class to work around a docs-page layout. But this changes what a reader lands on when following these links, which is worth your call before #1103 round 3 touchesdocs//tests/on this question.JarryShaw commentedon Oct 28, 2026
ProtocolBaseis the internal hidden API.Protocolis the one exposing the APIs and attributes. So i'd prefer we keep referring onProtocolwhenever possible.JarryShaw commentedon Oct 28, 2026
Got it — prefer
Protocolin prose/cross-references wherever a member is reachable through it, even though it's actually defined onProtocolBase. This reverses #2415's main conversion (which went the other way) and the smaller version of the same conversion #2403... correction, #2408 already merged in theregisterdocs. Closing #2415 rather than reworking it (its core premise is now invalid) and will open a corrective PR reverting the merged change, plus fold the standardization ontoProtocolinto the next #1103 round.docs: prefer Protocol over ProtocolBase in plain cross-references (#1103
docs: prefer Protocol over ProtocolBase in cross-references, per the …
JarryShaw commentedon Oct 28, 2026
New refinement on the Protocol/ProtocolBase cross-reference rule: for the sites #2420 reverted to bare
ProtocolBase.X, use the split Sphinx form:meth:Protocol.X <...ProtocolBase.X>`` instead — display text always saysProtocol.X(for consistency), but the target points at `ProtocolBase.X` since that's where the actual documentation entry lives. Applying this to #2420's 21 reverted sites, and auditing whether this should extend to other `ProtocolBase.X` targets across the tree for the same reason.docs: display Protocol in ProtocolBase member cross-references (#1103)
docs: name Protocol in ProtocolBase member cross-references (#1103)
docs: retarget Protocol/ProtocolBase cross-references to match the #1103