docs(foundation): fourth whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• 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
• release — bumps the version or rolls up a distribution
• chore — anything else

The fourth whole-repo prose pass of #1103, over foundation, toolkit, dumpkit, interface and utilities. It changes prose only: every changed .py file's AST is unchanged once string expressions are blanked, except where a docstring is added or vendor template text is edited together with its generated const file.

Accuracy:

• Dumper's registration example passes ext by keyword; register_dumper
  takes it keyword-only, so the positional form raised TypeError.
• The strict -> reasm_strict rename and TraceFlow.register removal
  directives name 1.1.1, whose changelog records the 1.1.1.post2 change.

Cross-references:

• sys.excepthook and threading.excepthook are functions, so they use
  :func: and resolve through intersphinx.
• The IP reassembly page documents _detect_conflicts, which the IP data
  model and the IPv4 and IPv6 pages link to.
• The exceptions page documents _CaughtByCaller and says how it makes an
  error quiet.

Wording:

• "c.f." becomes "cf.", and the redundant "and etc." is dropped.
• A list item in the PCAP-NG engine's read_frame ends with a semicolon.

Refs #1103

[JarryShaw]

NEEDS CHANGES at 14f209f9e. docs/source/pcapkit/interface/index.rst:7 duplicates the pcapkit/interface/__init__.py docstring this PR edits and still says "and etc.", so it needs the same rewording. A second check: the new versionchanged:: 1.1.1 directives (extraction.py, interface/core.py, traceflow.py) name a change the prose dates to 1.1.1.post2, so they should follow the repo's existing convention for post-releases.

[JarryShaw]

Question for the owner: the three new versionchanged:: 1.1.1 directives (extraction.py, interface/core.py, traceflow.py) cover changes that first shipped in v1.1.1.post2. No directive in the repo names a post-release. The existing precedents disagree: const/pcapng.rst:64 names the parent release for a .post1 change, and const/reg.rst:96 names the next release. Should a post-release change name the parent release (as now), the next release, or the post-release itself? My recommendation is the parent, as the PR has it, because the prose already says 1.1.1.post2. The docs/source/pcapkit/interface/index.rst fix is pushed.

[JarryShaw]

GOOD TO GO at 8a4ad4ac6. A Sonnet re-review confirmed that interface/index.rst now matches the module docstring word for word, and that no other rst copy of an edited docstring keeps the old wording. The versionchanged:: 1.1.1 question above is still open for the owner, so the needs: decision label stays.

[github-actions]

Coverage: 90.07% (unit tier, Python 3.15, 71e4f30d4, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2504	70	792	36	96.54%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2916	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17411	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	522	2	158	4	99.12%
pcapkit/vendor	4431	2341	1018	156	43.64%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

GOOD TO GO at 71e4f30d4. interface/index.rst is back to main's blob, so this PR no longer overlaps #1912, and merge-tree against #1912 is clean. The module docstring now matches #1912's page text line for line. "Interfaces and constants" is accurate: extract/reassemble/trace are the only functions, and every other name in __all__ is a string constant. The versionchanged:: 1.1.1 question above is still open.

[JarryShaw]

Changes in post releases marked by their own post releases or the next release - parent release does not contain the changes and can be confusing.

[JarryShaw]

Understood. A post-release change gets its own post-release in the directive, or the next release, because the parent release never shipped it. I'll change the three directives to 1.1.1.post2. I'll also audit every other versionadded/versionchanged/versionremoved in the repo that names a parent release for a post-release change, docs/source/pcapkit/const/pcapng.rst:64 (1.1.0 for a .post1 change) among them, and fix them in this PR.

[JarryShaw]

GOOD TO GO at acb16fb85. A Sonnet re-review checked each change against the tags on either side of it. reasm_strict first appears at v1.1.1.post2. TraceFlowBase.register is gone at v1.1.1.post2. OptionType.__int__ and its siblings arrive at v1.1.0.post1. Its own scan covered every directive in pcapkit/ and docs/, and only 1.1.0, 1.1.1, 1.3.1 and 1.3.3 have post-release tags. All the unchanged directives it spot-checked are correct, or name the next release. The MOVED_NOTES pin was moved, not weakened, and merge-tree against main is clean.