docs(protocols): tighten misc protocol prose and correct the record docs (#719)

[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (docstrings and comments only)
• make test passes, and a test case covers the change (prose only; existing modules run one per process)
• Changelog entry: 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

Slice of #719 for pcapkit/protocols/misc/. Cuts timed context and restatement, keeps rationale, fixes prose the code contradicts:

• pcapng.py: name-resolution record docs said "systemd journal export"; option table omitted the four opt_custom_* options; packet-block lists said ISB where PACKET_TYPES holds SPB; register's Warns now states that the first explicit registration over a built-in module descriptor still warns (probed); _get_linktype summary was truncated.
• pcap/frame.py: len/cap_len rationale kept (Wireshark names), commit dates kept because toolkit/pcapng.py points to them.
• null.py: notes payload is the instance itself; null.py/raw.py attribute docs cited pcapkit.protocols.null.

Not fixed (code): ns_dnsname/ns_dnsIP4addr/ns_dnsIP6addr error strings say "systemd Journal Export Block" but the check is for a Name Resolution Block (pcapng.py read and make sides); register_record warning string says the same.

Sphinx -n, branch vs main, misc files: 27 vs 27 warnings, none new. Tests: all tests/protocols/misc/ modules, test_pcapng_regression.py, test_generated_pcap_runtime.py, test_docstring_contract.py, tests/project pass.

AST guard (docstrings stripped, vs origin/main):

File	Identical
pcapkit/protocols/misc/null.py	True
pcapkit/protocols/misc/pcap/frame.py	True
pcapkit/protocols/misc/pcapng.py	True
pcapkit/protocols/misc/raw.py	True
__init__.py, pcap/__init__.py, pcap/header.py	untouched

[JarryShaw]

Cross-review verdict on ba80e3ccb: NEEDS CHANGES (ran on Opus; authored on Sonnet). One finding. I reproduced it.

pcapng.py:899-901: the new PCAPNG.register Warns: text says the first explicit registration of a built-in class "still warns". That is true only until a frame of that link type has been decoded. On a lookup hit, ProtocolBase._lookup_next_layer writes the resolved class back into the registry (protocol.py:1759). The reviewer extracted examples/captures/dhcp.pcapng (4 frames, Ethernet:IPv4:UDP:Raw), and afterwards the entry was the Ethernet class and the first explicit register(ETHERNET, Ethernet) raised 0 warnings. Suggested wording: "…a built-in entry holds an unresolved module descriptor until a frame of that link type is first decoded, so registering the same class warns before then and is silent after." The same case makes #1034's "warns once" false, and that verdict is now retracted.

Confirmed:

• Name Resolution relabel: __record__ maps exactly the three nrb_record_* values.
• opt_custom row: all four codes map to custom.
• PACKET_TYPES: it is EPB, SPB and Packet.
• NoPayload: .payload is the same object, which is stronger than the repo's earlier finding of merely the same type.
• Module path: pcapkit.protocols.null does not import, and pcapkit.protocols.misc.null does.
• Rationale: all of it is kept, including the commit dates that toolkit/pcapng.py:270-277 points to.
• Inherited claims: the prepare / StreamEOFError and _read_fileng short-read claims are both verified.

Nit: "or use the protocol chain" does not apply to a bare NoPayload, because its protochain is None. The runtime error strings that name the journal block are code and are tracked separately in #1038.

[JarryShaw]

Cross-review verdict on b83eb7d62: GOOD TO GO (ran on Opus; authored on Sonnet). The resolution clause is gone, and every remaining clause matches the code.

What changed. PCAPNG.register's Warns: text now says only that the warning fires when the incumbent differs, and that an unresolved module descriptor counts as different from the class it names. It no longer claims anything about when an entry resolves. That claim was what rounds 1 and 2 got wrong: a first register resolves an entry, and so does a decode.

Probes, each in a fresh process:

• Register first, twice: 1 warning, then 0.
• Extract dhcp.pcapng, then register the same class: 0 warnings.
• Register a different class: 1 warning in either order.
• Pass a ModuleDescriptor over the built-in entry: 1 warning, because register resolves its argument to the class first.

The register_linktype sentence is true. It calls Frame.register and then PCAPNG.register (foundation/registry/protocols.py:411-412). The two registries are separate objects (Frame.__proto__ is PCAPNG.__proto__ → False). On a fresh link type it raises 0 warnings, repeating the same class is silent, and a different class raises exactly 2 warnings, one per registry.

Scope. The only change since round 2 is that Warns: hunk. All four misc/ files are AST-identical to main. Every round-1 confirmation still holds.