Skip to content

docs: close the #719 sweep's last three leftovers (#719) - #1056

Merged
JarryShaw merged 2 commits into
mainfrom
docs/719-final-leftovers
Oct 6, 2026
Merged

JarryShaw merged 2 commits into
mainfrom
docs/719-final-leftovers

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • fix — corrects a defect
  • feat — adds a feature
  • perf — changes performance, not behaviour
  • refactor — changes neither behaviour nor performance
  • test — tests only
  • docs — documentation only
  • ci — workflows or build tooling
  • chore — anything else

Description of your pull request and other information

Part of #719. It closes the sweep's last three leftovers:

  1. registry.rst gains .. autofunction:: for register_protocol_code. feat(protocols): opt-in code= registration with enum-type inference for Protocol/ProtocolBase #570 exported it in three __all__ lists but never documented it, so ext.rst's :func: reference resolved to nothing. Its docstring now links ProtocolBase rather than the undocumented __init_subclass__, which would have added a new warning.
  2. utilities/logging.py: "pre-1.4" becomes "pre-1.5". The stderr handler is still attached at v1.4.1.post2, and Logging integration: make the logger a library citizen, and use it #384 first ships in v1.5.0a1.
  3. toolkit/*.py: all eight module docstrings claimed the functions return "with a flag". They return data or None, and the pypcap/pcap_ct functions raise UnsupportedCall. The docstrings now match docs/source/pcapkit/toolkit/*.rst, and the PCAP-NG-NG typo is fixed.

Sphinx (-b dummy -n): 1290 warnings on main and 1289 on this branch, so 0 are new and the register_protocol_code one is gone.

File (AST with every bare-string Expr stripped, main vs branch) Result
pcapkit/toolkit/{dpkt,pcap,pcap_ct,pcapng,pypcap,pypcapfile,pyshark,scapy}.py identical (8/8)
pcapkit/foundation/registry/protocols.py, pcapkit/utilities/logging.py identical (2/2)

@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Oct 6, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Cross-review verdict on 828d5064f: GOOD TO GO (ran on Sonnet; author Opus).

  • register_protocol_code was missed, not hidden. It has a full docstring (protocols.py:301), it is in four __all__ lists, and it has been undocumented since feat(protocols): opt-in code= registration with enum-type inference for Protocol/ProtocolBase #570. The new autofunction sits directly after register_protocol. The rewritten docstring is accurate: ProtocolBase.__init_subclass__ (protocol.py:1027) takes code=.
  • "pre-1.5" is correct. At v1.4.1.post2 the stderr handler is attached unconditionally (logging.py:55). git tag --contains 62a250abf puts Logging integration: make the logger a library citizen, and use it #384 first in v1.5.0a1.
  • The toolkit docstrings now hold for all eight modules. The pcap, pcapng, dpkt and scapy adapters return data or None. The pypcap and pcap_ct adapters always raise UnsupportedCall. pypcapfile.ipv6_reassembly's raise is covered by the .. important:: block. Each leading sentence matches its .rst page. The "PCAP-NG Tools" title and its underline are both 13 characters.
  • AST is identical for all 10 files, and every one has a real text diff.
  • Tests: test_conventions_doc_claims 37 passed, test_documentation_claims 3 passed, test_docstring_contract 7 passed.

Nit (pre-existing, mirrored in 3rdparty.rst): pyshark.py says "reassembly and flow tracing adapters" but defines only tcp_traceflow.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 6, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
@JarryShaw
JarryShaw merged commit ef0964c into main Oct 6, 2026
72 checks passed
@JarryShaw
JarryShaw deleted the docs/719-final-leftovers branch October 6, 2026 01:43
@JarryShaw JarryShaw added review: running A cross-review is in flight against the current head - no verdict yet and removed review: good-to-go Cross-review at the current head says ready; CI state is separate review: running A cross-review is in flight against the current head - no verdict yet labels Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant