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.197 remaining items
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
docs: #1103 round 8 -- finish the Protocol/ProtocolBase cross-referen…
JarryShaw commentedon Oct 29, 2026
Next round? Or we done?
JarryShaw commentedon Oct 29, 2026
My read: diminishing returns, but not quite zero yet.
Round 8 found far less than round 7 — mostly small prose drift, plus one genuine but unrelated defect (the vendor crawler
dataargument bug, now fixed in #2430). What's left and known:protocol.pyitself still has ~11 unqualifiedProtocolBase.<member>roles, andtransport.py'sProtocolBase._lookup_registrylink (added by fix(reassembly): the deferred TCP analyser dispatches on AppType, not bare ports #2421) — same mechanical flip as the 37+ sites already done, just not yet swept.constshould be usable as a commit-type label elsewhere (process.rst's own convention doc), and twoconf.pycomments claiming "Sphinx 9.1" behavior that should be re-verified against the pinned 9.2.0 docs venv.Recommendation: one more round scoped to just those four items (mechanical flip + two verifications), then stop unless that round turns up something new on its own. Not recommending an open-ended continuation — the ratio of effort to findings has been dropping each round.
JarryShaw commentedon Oct 29, 2026
Round 9 it is — dispatching now, scoped to the 4 known items.
JarryShaw commentedon Oct 29, 2026
Noted —
constshould be a valid commit-type (it already exists as a label; this extends it to the PR template checkbox /process.rst's documented set). Relaying to the round-9 worker to implement rather than just report.