docs(protocols): tighten the schema prose and cut timed context (#719)

[JarryShaw]

• 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
• 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?

• docs — documentation only

---

Description of your pull request and other information

Slice of #719 covering pcapkit/protocols/schema/: 13 files, docstrings and comments only (+422 / -658). Cuts "used to" / "until #NNN" / measured-before-the-fix prose, keeps the rationale behind each guard, fixes a HEADERS flags docstring that named DATA frames, and a improt typo.

Not touched (nothing to cut found): link/*, application/{ftp,httpv1,ngap,ospf,__init__}, internet/{ah,esp,ipx,ipv6,ipv6_ext,ipv6_frag,__init__}, misc/{__init__,null,raw}, misc/pcap/{header,__init__}, transport/__init__. mh.py, hip.py, pcapng.py were only partly rewritten (timed context and issue citations); their remaining RFC prose is unchanged.

Checks: sphinx-build -b dummy -n fresh dirs, branch vs main, schema-file warnings 51 vs 51, none new. tests/project, tests/test_docstring_contract.py, the three tests/protocols/schema/ modules and test_option_roundtrip_unit.py pass, one module per process.

AST guard (docstrings stripped, vs origin/main): all 13 files True.

file	identical AST
schema.py	True
transport/{tcp,udp,sctp}.py	True
internet/{ipv4,ipv6_route,ipv6_opts,hopopt,hip,mh}.py	True
misc/pcapng.py, misc/pcap/frame.py	True
application/httpv2.py	True

[JarryShaw]

Cross-review verdict on c8e3cd875: GOOD TO GO (ran on Opus; authored on Sonnet). Docstrings and comments only, 13 of the 37 schema/ files. The PR body states that the coverage is partial.

EnumSchema.register note is correct. Same schema object: no warning. Different object: one warning. There is no write-back path here like ProtocolBase's, because __enum__ entries are classes, not ModuleDescriptors, so the note needs no state qualifier. The removed cross-reference to register_protocol was accurate but redundant: the note now states the condition directly.

registry properties are correct. Both exist (EnumMeta and EnumSchema). The class lookup resolves through the metaclass, an instance resolves to the same _EnumRegistry, and EngineMeta.registry describes the same split. The if code is not None opt-in is untouched.

IPv4 Stream ID cut is correct, and my own earlier note was stale. SIDOption.sid is UInt16Field on main (ipv4.py:520); 04b9c3747 (#534, #537) narrowed it. The removed "6-octet UInt32Field" narrative was history, not a live defect.

Arithmetic matches the declared fields: MPTCP Fastclose 12 octets; MP_CAPABLE 12 and 20; HIP encrypted_data_len and parameter_total_len; the locator-set byte count. HTTP/2 has six Flags(0) sites and five flags=None sites, and HeadersFrame.Flags now reads HEADERS. All listed rationale survives.

Found along the way, filed as #1042: a pre-existing defect where three of the five RFC 8684 MP_CAPABLE lengths fail to parse. It is outside this PR's scope.