From 639b791b4560df0b47c08e817a0f2e879650b7d1 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Mon, 19 Oct 2026 00:25:33 -0400 Subject: [PATCH] docs(protocols): fourth whole-repo pass over link and transport protocols (#1103) Rendering: - Drop the inline `DefaultDict[...]:` type prefix from the registry attribute comments in link, loopback, TCP, UDP and SCTP; it rendered a second, unlinked Type field naming private aliases and a key type that disagreed with the signature. Accuracy: - L2TP: cite RFC 3931 section 4.1.1.1 for the session-header quote and section 4.7.2 for port 1701 being shared with L2TPv2. - L2TP: HTTP._guess_version identifies the version first and trial-parses only as a last resort, as the docs page already said. Wording: - "c.f." becomes "see"; "implements extractor" gains its article. - UDP length field: "header included"; a missing full stop in the TCP schema. Refs #1103 --- docs/source/pcapkit/protocols/link/c_tag.rst | 2 +- .../pcapkit/protocols/link/ethernet.rst | 2 +- docs/source/pcapkit/protocols/link/l2tp.rst | 2 +- docs/source/pcapkit/protocols/link/l2tpv2.rst | 2 +- .../pcapkit/protocols/link/loopback.rst | 2 +- docs/source/pcapkit/protocols/link/s_tag.rst | 2 +- .../pcapkit/protocols/transport/sctp.rst | 2 +- .../pcapkit/protocols/transport/tcp.rst | 2 +- .../pcapkit/protocols/transport/udp.rst | 4 +-- pcapkit/protocols/link/arp.py | 2 +- pcapkit/protocols/link/c_tag.py | 4 +-- pcapkit/protocols/link/ethernet.py | 2 +- pcapkit/protocols/link/l2tp.py | 23 ++++++------ pcapkit/protocols/link/l2tpv2.py | 6 ++-- pcapkit/protocols/link/link.py | 10 +++--- pcapkit/protocols/link/loopback.py | 15 ++++---- pcapkit/protocols/link/s_tag.py | 4 +-- pcapkit/protocols/schema/link/l2tp.py | 2 +- pcapkit/protocols/schema/transport/sctp.py | 4 +-- pcapkit/protocols/schema/transport/tcp.py | 6 ++-- pcapkit/protocols/schema/transport/udp.py | 2 +- pcapkit/protocols/transport/sctp.py | 36 +++++++++---------- pcapkit/protocols/transport/tcp.py | 28 +++++++-------- pcapkit/protocols/transport/transport.py | 2 +- pcapkit/protocols/transport/udp.py | 17 ++++----- 25 files changed, 93 insertions(+), 90 deletions(-) diff --git a/docs/source/pcapkit/protocols/link/c_tag.rst b/docs/source/pcapkit/protocols/link/c_tag.rst index be9d81a9b7..54bcdb6eac 100644 --- a/docs/source/pcapkit/protocols/link/c_tag.rst +++ b/docs/source/pcapkit/protocols/link/c_tag.rst @@ -4,7 +4,7 @@ C_Tag - 802.1Q Customer VLAN Tag Type .. module:: pcapkit.protocols.link.c_tag :mod:`pcapkit.protocols.link.c_tag` contains -:class:`~pcapkit.protocols.link.c_tag.C_Tag` only, which implements extractor for +:class:`~pcapkit.protocols.link.c_tag.C_Tag` only, which implements the extractor for the 802.1Q Customer VLAN Tag Type (C-Tag) [*]_, EtherType ``0x8100``. diff --git a/docs/source/pcapkit/protocols/link/ethernet.rst b/docs/source/pcapkit/protocols/link/ethernet.rst index fa67920c3d..47a2cfec88 100644 --- a/docs/source/pcapkit/protocols/link/ethernet.rst +++ b/docs/source/pcapkit/protocols/link/ethernet.rst @@ -5,7 +5,7 @@ Ethernet Protocol :mod:`pcapkit.protocols.link.ethernet` contains :class:`~pcapkit.protocols.link.ethernet.Ethernet` -only, which implements extractor for Ethernet +only, which implements the extractor for Ethernet Protocol [*]_, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/link/l2tp.rst b/docs/source/pcapkit/protocols/link/l2tp.rst index bfee94cd44..d90b758eef 100644 --- a/docs/source/pcapkit/protocols/link/l2tp.rst +++ b/docs/source/pcapkit/protocols/link/l2tp.rst @@ -54,7 +54,7 @@ the value 1 "to permit detection of L2F packets should they arrive intermixed wi L2TP packets". L2F is a separate protocol with its own header, so it is to be implemented as ``L2F``, the canonical name, with ``L2TPv1`` only as an alias in its :meth:`~pcapkit.protocols.protocol.Protocol.id` -- the relationship HTTP/3 has to -QUIC. c.f. :meth:`HTTPv1.id ` for +QUIC. See :meth:`HTTPv1.id ` for how a version-flavoured alias is spelled: canonical name first, alias second, since callers take element zero as canonical. diff --git a/docs/source/pcapkit/protocols/link/l2tpv2.rst b/docs/source/pcapkit/protocols/link/l2tpv2.rst index 12cb236f1b..8e000c682f 100644 --- a/docs/source/pcapkit/protocols/link/l2tpv2.rst +++ b/docs/source/pcapkit/protocols/link/l2tpv2.rst @@ -4,7 +4,7 @@ L2TPv2 - Layer Two Tunnelling Protocol version 2 .. module:: pcapkit.protocols.link.l2tpv2 :mod:`pcapkit.protocols.link.l2tpv2` contains -:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` only, which implements extractor +:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` only, which implements the extractor for the Layer Two Tunnelling Protocol version 2 (L2TPv2) [*]_ as specified by :rfc:`2661` -- a 16-bit tunnel ID and a 16-bit session ID, with the version nibble reading ``2``. It is dispatched from diff --git a/docs/source/pcapkit/protocols/link/loopback.rst b/docs/source/pcapkit/protocols/link/loopback.rst index a489d007c4..f31305f6fa 100644 --- a/docs/source/pcapkit/protocols/link/loopback.rst +++ b/docs/source/pcapkit/protocols/link/loopback.rst @@ -5,7 +5,7 @@ BSD Loopback Encapsulation :mod:`pcapkit.protocols.link.loopback` contains :class:`~pcapkit.protocols.link.loopback.Loopback` -only, which implements extractor for the BSD loopback +only, which implements the extractor for the BSD loopback encapsulation [*]_ of ``LINKTYPE_NULL`` and ``LINKTYPE_LOOP``, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/link/s_tag.rst b/docs/source/pcapkit/protocols/link/s_tag.rst index 409edab009..0c3b7d6593 100644 --- a/docs/source/pcapkit/protocols/link/s_tag.rst +++ b/docs/source/pcapkit/protocols/link/s_tag.rst @@ -4,7 +4,7 @@ S_Tag - 802.1ad Service VLAN Tag Type .. module:: pcapkit.protocols.link.s_tag :mod:`pcapkit.protocols.link.s_tag` contains -:class:`~pcapkit.protocols.link.s_tag.S_Tag` only, which implements extractor for +:class:`~pcapkit.protocols.link.s_tag.S_Tag` only, which implements the extractor for the 802.1ad Service VLAN Tag Type (S-Tag) [*]_, EtherType ``0x88A8``. Its structure, and all of its parsing and construction, come from diff --git a/docs/source/pcapkit/protocols/transport/sctp.rst b/docs/source/pcapkit/protocols/transport/sctp.rst index 7c66c5346d..dd0dcdd276 100644 --- a/docs/source/pcapkit/protocols/transport/sctp.rst +++ b/docs/source/pcapkit/protocols/transport/sctp.rst @@ -5,7 +5,7 @@ SCTP - Stream Control Transmission Protocol :mod:`pcapkit.protocols.transport.sctp` contains :class:`~pcapkit.protocols.transport.sctp.SCTP` only, -which implements extractor for Stream Control +which implements the extractor for Stream Control Transmission Protocol (SCTP) [*]_, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/transport/tcp.rst b/docs/source/pcapkit/protocols/transport/tcp.rst index 3096499d91..50aab04830 100644 --- a/docs/source/pcapkit/protocols/transport/tcp.rst +++ b/docs/source/pcapkit/protocols/transport/tcp.rst @@ -5,7 +5,7 @@ TCP - Transmission Control Protocol :mod:`pcapkit.protocols.transport.tcp` contains :class:`~pcapkit.protocols.transport.tcp.TCP` only, -which implements extractor for Transmission Control +which implements the extractor for Transmission Control Protocol (TCP) [*]_, whose structure is described as below: diff --git a/docs/source/pcapkit/protocols/transport/udp.rst b/docs/source/pcapkit/protocols/transport/udp.rst index 3dae90bf5a..17986ccf63 100644 --- a/docs/source/pcapkit/protocols/transport/udp.rst +++ b/docs/source/pcapkit/protocols/transport/udp.rst @@ -5,7 +5,7 @@ UDP - User Datagram Protocol :mod:`pcapkit.protocols.transport.udp` contains :class:`~pcapkit.protocols.transport.udp.UDP` only, -which implements extractor for User Datagram Protocol +which implements the extractor for User Datagram Protocol (UDP) [*]_, whose structure is described as below: ======= ========= ===================== =============================== @@ -13,7 +13,7 @@ Octets Bits Name Description ======= ========= ===================== =============================== 0 0 ``udp.srcport`` Source Port 2 16 ``udp.dstport`` Destination Port - 4 32 ``udp.len`` Length (header includes) + 4 32 ``udp.len`` Length (header included) 6 48 ``udp.checksum`` Checksum ======= ========= ===================== =============================== diff --git a/pcapkit/protocols/link/arp.py b/pcapkit/protocols/link/arp.py index ba00d309fc..18402ff476 100644 --- a/pcapkit/protocols/link/arp.py +++ b/pcapkit/protocols/link/arp.py @@ -450,7 +450,7 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p packed, and anything else is returned as given. Raises: - FieldValueError: If ``addr`` is a :obj:`bool` (c.f. + FieldValueError: If ``addr`` is a :obj:`bool` (see :func:`~pcapkit.corekit.fields.ipaddress.parse_ip_address`). ProtocolError: If ``ptype`` is neither IPv4 nor IPv6 and ``addr`` is a :data:`str` that is not *hex* encoded. diff --git a/pcapkit/protocols/link/c_tag.py b/pcapkit/protocols/link/c_tag.py index 7beaf8bcea..0d94745fe1 100644 --- a/pcapkit/protocols/link/c_tag.py +++ b/pcapkit/protocols/link/c_tag.py @@ -5,7 +5,7 @@ .. module:: pcapkit.protocols.link.c_tag :mod:`pcapkit.protocols.link.c_tag` contains -:class:`~pcapkit.protocols.link.c_tag.C_Tag` only, which implements extractor for +:class:`~pcapkit.protocols.link.c_tag.C_Tag` only, which implements the extractor for the 802.1Q Customer VLAN Tag Type (C-Tag, formerly the Q-Tag) [*]_, EtherType ``0x8100``. Its structure, and all of its parsing and construction, come from :class:`~pcapkit.protocols.link.vlan.VLAN`; this class adds only the tag's own @@ -41,7 +41,7 @@ # resolves an omitted schema by looking the *subclass name* up in # :mod:`pcapkit.protocols.schema`, and assigns unconditionally -- so leaving them # off would silently bind ``Schema_Raw``/``Data_Raw`` rather than falling back to -# the base class's pair. c.f. :class:`~pcapkit.protocols.application.rarp.RARP`, which +# the base class's pair. See :class:`~pcapkit.protocols.application.rarp.RARP`, which # restates them for the same reason. class C_Tag(VLAN, schema=Schema_VLAN, data=Data_VLAN): """This class implements 802.1Q Customer VLAN Tag Type. diff --git a/pcapkit/protocols/link/ethernet.py b/pcapkit/protocols/link/ethernet.py index f18672f103..f42574abde 100644 --- a/pcapkit/protocols/link/ethernet.py +++ b/pcapkit/protocols/link/ethernet.py @@ -6,7 +6,7 @@ :mod:`pcapkit.protocols.link.ethernet` contains :class:`~pcapkit.protocols.link.ethernet.Ethernet` -only, which implements extractor for Ethernet +only, which implements the extractor for Ethernet Protocol [*]_, whose structure is described as below: diff --git a/pcapkit/protocols/link/l2tp.py b/pcapkit/protocols/link/l2tp.py index 3cb1746f98..c5ced29afc 100644 --- a/pcapkit/protocols/link/l2tp.py +++ b/pcapkit/protocols/link/l2tp.py @@ -44,7 +44,7 @@ Binding :class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` at 115 instead does not work (:issue:`548`), and is recorded so it is not proposed again. Over IP the v3 -session header is, in :rfc:`3931` §4.1.1's own words, *"free of any restrictions +session header is, in :rfc:`3931` §4.1.1.1's own words, *"free of any restrictions imposed by coexistence with L2TPv2 and L2F"* -- a data message opens with the raw 32-bit Session ID and carries **no version nibble at all**, so there is nothing a v2 parser could test to recognise that the datagram is not its own. Measured, @@ -60,7 +60,7 @@ with L2TP packets". L2F is a separate protocol with its own header. It is therefore to be implemented as ``L2F``, the canonical name, carrying ``L2TPv1`` only as an alias in its :meth:`~pcapkit.protocols.protocol.Protocol.id` -- -the same relationship HTTP/3 has to QUIC. c.f. +the same relationship HTTP/3 has to QUIC. See :meth:`HTTPv1.id ` for how a version-flavoured alias is spelled: canonical name first, alias second, since callers take element zero as canonical. @@ -73,22 +73,23 @@ :meth:`L2TPv2.read ` does **check** it, and refuses anything other than ``2``. That is the half of the mechanism which is useful with no other version implemented: it keeps v3 traffic on port -1701 (:rfc:`3931` §4.1.2 shares the port, so this is ordinary capture +1701 (:rfc:`3931` §4.7.2 shares the port, so this is ordinary capture traffic rather than a corner case) from being reported as v2 with a tunnel and session ID read out of v3's Control Connection ID. When another version lands, the remaining half -- delegation rather than refusal -- already has a precedent in :class:`~pcapkit.protocols.application.http.HTTP`, which reads a version and -delegates to a per-version class. L2TP is the easier case: HTTP has to -*trial-parse* each candidate in -:meth:`~pcapkit.protocols.application.http.HTTP._guess_version` because the wire -format carries no version field, whereas L2TP states its version explicitly in -those four bits. So a deterministic switch on ``Ver`` is enough, and no new -registry is needed -- the class bound at UDP 1701 reads two octets, masks out the -nibble, and hands the datagram to the matching class. Note the switch belongs on +delegates to a per-version class. L2TP is the easier case: +:meth:`~pcapkit.protocols.application.http.HTTP._guess_version` has to *infer* +the version -- recognising the HTTP/2 preface or an HTTP/1 start line, else +trial-parsing each candidate -- because HTTP's wire format carries no version +field, whereas L2TP states its version explicitly in those four bits. So a +deterministic switch on ``Ver`` is enough, and no new registry is needed -- the +class bound at UDP 1701 reads two octets, masks out the nibble, and hands the +datagram to the matching class. Note the switch belongs on the **UDP** path only: over IP protocol 115 there is no nibble to switch on, per -the §4.1.1 note above. +the §4.1.1.1 note above. .. [*] https://en.wikipedia.org/wiki/Layer_2_Tunneling_Protocol diff --git a/pcapkit/protocols/link/l2tpv2.py b/pcapkit/protocols/link/l2tpv2.py index 4b35073412..4ff88ad976 100644 --- a/pcapkit/protocols/link/l2tpv2.py +++ b/pcapkit/protocols/link/l2tpv2.py @@ -5,7 +5,7 @@ .. module:: pcapkit.protocols.link.l2tpv2 :mod:`pcapkit.protocols.link.l2tpv2` contains -:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` only, which implements extractor +:class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` only, which implements the extractor for the Layer Two Tunnelling Protocol version 2 (L2TPv2) [*]_ as specified by :rfc:`2661` -- a 16-bit tunnel ID and a 16-bit session ID, with the version nibble reading ``2``. Its structure is described as below: @@ -90,7 +90,7 @@ class L2TPv2(L2TP[Data_L2TP, Schema_L2TP], Only the :rfc:`2661` framing is read: :meth:`read` refuses a datagram whose version nibble is not ``2``, so a v3 datagram arriving on port 1701 - (:rfc:`3931` §4.1.2 shares the port) degrades to + (:rfc:`3931` §4.7.2 shares the port) degrades to :class:`~pcapkit.protocols.misc.raw.Raw` instead of being reported as v2. .. versionadded:: 1.5.0 @@ -135,7 +135,7 @@ def version(self) -> 'Literal[2]': Always ``2``: :rfc:`2661` fixes the version nibble, and a datagram carrying any other value is a different protocol reached through a - different class. c.f. :class:`~pcapkit.protocols.link.l2tp.L2TP`. + different class. See :class:`~pcapkit.protocols.link.l2tp.L2TP`. This is enforced rather than merely asserted -- :meth:`read` refuses a datagram whose nibble is not ``2``, so this hard-coded answer cannot diff --git a/pcapkit/protocols/link/link.py b/pcapkit/protocols/link/link.py index 3ddf5c6815..0a3fd1bb67 100644 --- a/pcapkit/protocols/link/link.py +++ b/pcapkit/protocols/link/link.py @@ -68,9 +68,11 @@ class Link(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=abstra #: Layer of protocol. __layer__ = 'Link' # type: Literal['Link'] - #: DefaultDict[int, ModuleDescriptor[ProtocolBase] | ~typing.Type[ProtocolBase]]: Protocol index mapping for decoding next layer, - #: c.f. :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding next layer, see + #: :meth:`self._decode_next_layer + #: ` & + #: :meth:`self._import_next_layer + #: `. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), { @@ -92,7 +94,7 @@ class Link(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=abstra Enum_EtherType.Internet_Protocol_version_4: ModuleDescriptor('pcapkit.protocols.internet.ipv4', 'IPv4'), Enum_EtherType.Internet_Protocol_version_6: ModuleDescriptor('pcapkit.protocols.internet.ipv6', 'IPv6'), - # c.f., https://en.wikipedia.org/wiki/EtherType#Values + # see https://en.wikipedia.org/wiki/EtherType#Values 0x8137: ModuleDescriptor('pcapkit.protocols.internet.ipx', 'IPX'), }, ) # type: DefaultDict[int | Enum_EtherType, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]] diff --git a/pcapkit/protocols/link/loopback.py b/pcapkit/protocols/link/loopback.py index f197977ce7..bb025a7f4c 100644 --- a/pcapkit/protocols/link/loopback.py +++ b/pcapkit/protocols/link/loopback.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.link.loopback` contains :class:`~pcapkit.protocols.link.loopback.Loopback` -only, which implements extractor for the BSD loopback +only, which implements the extractor for the BSD loopback encapsulation [*]_ of ``LINKTYPE_NULL`` and ``LINKTYPE_LOOP``, whose structure is described as below: @@ -117,12 +117,13 @@ class Loopback(Link[Data_Loopback, Schema_Loopback], # Defaults. ########################################################################## - #: DefaultDict[int, ModuleDescriptor[ProtocolBase] | ~typing.Type[ProtocolBase]]: Protocol index - #: mapping for decoding next layer, - #: c.f. :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. - #: Keyed by address family rather than by EtherType, so this class keeps a - #: registry of its own instead of sharing :attr:`Link.__proto__ + #: Protocol index mapping for decoding next layer, see + #: :meth:`self._decode_next_layer + #: ` & + #: :meth:`self._import_next_layer + #: `. Keyed by + #: address family rather than by EtherType, so this class keeps a registry + #: of its own instead of sharing :attr:`Link.__proto__ #: `. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), diff --git a/pcapkit/protocols/link/s_tag.py b/pcapkit/protocols/link/s_tag.py index 140c03884c..68c17f4dea 100644 --- a/pcapkit/protocols/link/s_tag.py +++ b/pcapkit/protocols/link/s_tag.py @@ -5,7 +5,7 @@ .. module:: pcapkit.protocols.link.s_tag :mod:`pcapkit.protocols.link.s_tag` contains -:class:`~pcapkit.protocols.link.s_tag.S_Tag` only, which implements extractor for +:class:`~pcapkit.protocols.link.s_tag.S_Tag` only, which implements the extractor for the 802.1ad Service VLAN Tag Type (S-Tag) [*]_, EtherType ``0x88A8``. Its structure, and all of its parsing and construction, come from :class:`~pcapkit.protocols.link.vlan.VLAN`; this class adds only the tag's own @@ -63,7 +63,7 @@ def alias(self) -> 'Literal["802.1ad"]': """Acronym of corresponding protocol.""" return '802.1ad' - #: NOTE: c.f. :attr:`C_Tag.info_name ` + #: NOTE: see :attr:`C_Tag.info_name ` #: -- spelled out deliberately, since it is what keeps a stacked service tag #: and customer tag apart in the parsed info dict. @property diff --git a/pcapkit/protocols/schema/link/l2tp.py b/pcapkit/protocols/schema/link/l2tp.py index 9ea029e0ef..4aa0e465fd 100644 --- a/pcapkit/protocols/schema/link/l2tp.py +++ b/pcapkit/protocols/schema/link/l2tp.py @@ -108,7 +108,7 @@ class L2TP(Schema): ) #: Payload of L2TP packet. payload: 'bytes' = PayloadField(length=l2tp_payload_length) - #: Octets captured past the Length field, c.f. + #: Octets captured past the Length field, see #: :attr:`IPv4.trailer `. #: Always empty when the ``L`` flag is clear, since the payload then takes #: the rest of the datagram. diff --git a/pcapkit/protocols/schema/transport/sctp.py b/pcapkit/protocols/schema/transport/sctp.py index dc624614b0..58f5d1060e 100644 --- a/pcapkit/protocols/schema/transport/sctp.py +++ b/pcapkit/protocols/schema/transport/sctp.py @@ -871,7 +871,7 @@ def whole_chunks_length(data: 'bytes') -> 'int': Returns: Number of octets up to the end of the last chunk whose declared ``length`` octets are all present, with as much of its padding as there - is, c.f. :func:`padding_length`. A ``length`` below the four-octet chunk + is, see :func:`padding_length`. A ``length`` below the four-octet chunk header (:rfc:`9260#section-3.2`) delimits nothing, so the run stops there too; four zero octets would otherwise read as a DATA chunk. @@ -957,7 +957,7 @@ class SCTP(Schema): type_name='type', registry=Chunk.registry, ) - #: Octets captured after the last whole chunk, c.f. :class:`ChunkListField` + #: Octets captured after the last whole chunk, see :class:`ChunkListField` #: and :attr:`IPv4.trailer `. trailer: 'bytes' = PayloadField(default=b'') diff --git a/pcapkit/protocols/schema/transport/tcp.py b/pcapkit/protocols/schema/transport/tcp.py index b0f8e717a1..3148f8a56c 100644 --- a/pcapkit/protocols/schema/transport/tcp.py +++ b/pcapkit/protocols/schema/transport/tcp.py @@ -898,7 +898,7 @@ class MPTCPJoinSYNACK(MPTCPJoin): }) #: Address ID. addr_id: 'int' = UInt8Field() - #: Sender's truncated HMAC + #: Sender's truncated HMAC. hmac: 'bytes' = BytesField(length=8) #: Sender's random number. nonce: 'int' = UInt32Field() @@ -953,7 +953,7 @@ class MPTCPDSS(MPTCP, code=Enum_MPTCPOption.DSS): #: Data sequence number. #: #: 4 octets when ``M`` is set, 8 when ``m`` is set as well, absent otherwise -- - #: :rfc:`8684` section 3.3 figure 9. C.f. :func:`mptcp_dss_dsn_selector`. + #: :rfc:`8684` section 3.3 figure 9. See :func:`mptcp_dss_dsn_selector`. dsn: 'int' = SwitchField( selector=mptcp_dss_dsn_selector, ) @@ -967,7 +967,7 @@ class MPTCPDSS(MPTCP, code=Enum_MPTCPOption.DSS): UInt16Field(), lambda pkt: pkt['flags']['M'], ) - #: Checksum (if negotiated, c.f. :func:`mptcp_dss_checksum`). + #: Checksum (if negotiated, see :func:`mptcp_dss_checksum`). checksum: 'bytes' = ConditionalField( BytesField(length=2), mptcp_dss_checksum, diff --git a/pcapkit/protocols/schema/transport/udp.py b/pcapkit/protocols/schema/transport/udp.py index b6d127deaa..6d0a795a7b 100644 --- a/pcapkit/protocols/schema/transport/udp.py +++ b/pcapkit/protocols/schema/transport/udp.py @@ -34,7 +34,7 @@ class UDP(Schema): #: Payload. A Length below the header's own 8 octets leaves the length #: negative, which takes the rest of the datagram. payload: 'bytes' = PayloadField(length=lambda pkt: pkt['len'] - 8) - #: Octets captured past the Length field, c.f. + #: Octets captured past the Length field, see #: :attr:`IPv4.trailer `. trailer: 'bytes' = PayloadField(default=b'') diff --git a/pcapkit/protocols/transport/sctp.py b/pcapkit/protocols/transport/sctp.py index 1cddbd1b62..1a4ec1229a 100644 --- a/pcapkit/protocols/transport/sctp.py +++ b/pcapkit/protocols/transport/sctp.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.transport.sctp` contains :class:`~pcapkit.protocols.transport.sctp.SCTP` only, -which implements extractor for Stream Control +which implements the extractor for Stream Control Transmission Protocol (SCTP) [*]_, whose structure is described as below: @@ -448,10 +448,11 @@ class SCTP(Transport[Data_SCTP, Schema_SCTP], #: Payload protocol identifier of the first DATA chunk found in the packet. _ppid = None # type: Optional[Enum_PayloadProtocolIdentifier] - #: DefaultDict[int, ModuleDescriptor[ProtocolBase] | ~typing.Type[ProtocolBase]]: Protocol - #: index mapping for decoding next layer, c.f. - #: :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding next layer, see + #: :meth:`self._decode_next_layer + #: ` & + #: :meth:`self._import_next_layer + #: `. #: #: Important: #: Keyed by the DATA chunk's *payload protocol identifier* (PPID), **not** @@ -469,8 +470,7 @@ class SCTP(Transport[Data_SCTP, Schema_SCTP], }, ) # type: DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]] - #: DefaultDict[Enum_Chunk, str | tuple[ChunkParser, ChunkConstructor]]: Chunk - #: type to method mapping, c.f. :meth:`_read_sctp_chunks` and + #: Chunk type to method mapping, see :meth:`_read_sctp_chunks` and #: :meth:`_make_sctp_chunks`. Method names are expected to be referred to #: the class by ``_read_chunk_${name}`` and ``_make_chunk_${name}``, and if #: such name not found, the value should then be a method that can parse the @@ -494,12 +494,11 @@ class SCTP(Transport[Data_SCTP, Schema_SCTP], }, ) # type: DefaultDict[int, str | tuple[ChunkParser, ChunkConstructor]] - #: DefaultDict[Enum_Parameter, str | tuple[ParameterParser, ParameterConstructor]]: Chunk - #: parameter type to method mapping, c.f. :meth:`_read_sctp_parameters` - #: and :meth:`_make_sctp_parameters`. Method names are expected to be - #: referred to the class by ``_read_param_${name}`` and - #: ``_make_param_${name}``, and if such name not found, the value should then - #: be a method that can parse the parameter by itself. + #: Chunk parameter type to method mapping, see + #: :meth:`_read_sctp_parameters` and :meth:`_make_sctp_parameters`. Method + #: names are expected to be referred to the class by ``_read_param_${name}`` + #: and ``_make_param_${name}``, and if such name not found, the value should + #: then be a method that can parse the parameter by itself. __parameter__ = collections.defaultdict( lambda: 'donone', { @@ -514,12 +513,11 @@ class SCTP(Transport[Data_SCTP, Schema_SCTP], }, ) # type: DefaultDict[int, str | tuple[ParameterParser, ParameterConstructor]] - #: DefaultDict[Enum_CauseCode, str | tuple[CauseParser, CauseConstructor]]: Error - #: cause code to method mapping, c.f. :meth:`_read_sctp_causes` and - #: :meth:`_make_sctp_causes`. Method names are expected to be referred to the - #: class by ``_read_cause_${name}`` and ``_make_cause_${name}``, and if such - #: name not found, the value should then be a method that can parse the error - #: cause by itself. + #: Error cause code to method mapping, see :meth:`_read_sctp_causes` and + #: :meth:`_make_sctp_causes`. Method names are expected to be referred to + #: the class by ``_read_cause_${name}`` and ``_make_cause_${name}``, and if + #: such name not found, the value should then be a method that can parse the + #: error cause by itself. __cause__ = collections.defaultdict( lambda: 'donone', { diff --git a/pcapkit/protocols/transport/tcp.py b/pcapkit/protocols/transport/tcp.py index 311516e5fa..eeaa3b988a 100644 --- a/pcapkit/protocols/transport/tcp.py +++ b/pcapkit/protocols/transport/tcp.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.transport.tcp` contains :class:`~pcapkit.protocols.transport.tcp.TCP` only, -which implements extractor for Transmission Control +which implements the extractor for Transmission Control Protocol (TCP) [*]_, whose structure is described as below: @@ -333,10 +333,11 @@ class TCP(Transport[Data_TCP, Schema_TCP], # Defaults. ########################################################################## - #: DefaultDict[int, ModuleDescriptor[ProtocolBase] | ~typing.Type[ProtocolBase]]: Protocol - #: index mapping for decoding next layer, c.f. - #: :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding next layer, see + #: :meth:`self._decode_next_layer + #: ` & + #: :meth:`self._import_next_layer + #: `. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), { @@ -367,12 +368,11 @@ class TCP(Transport[Data_TCP, Schema_TCP], }, ) - #: DefaultDict[Enum_Option, str | tuple[OptionParser, OptionConstructor]]: Option - #: code to method mapping, c.f. :meth:`_read_tcp_options` and + #: Option code to method mapping, see :meth:`_read_tcp_options` and #: :meth:`_make_tcp_options`. Method names are expected to be referred to #: the class by ``_read_mode_${name}`` and ``_make_mode_${name}``, and if - #: such name not found, the value should then be a method that can parse - #: the option by itself. + #: such name not found, the value should then be a method that can parse the + #: option by itself. __option__ = collections.defaultdict( lambda: 'donone', { @@ -401,11 +401,11 @@ class TCP(Transport[Data_TCP, Schema_TCP], }, ) # type: DefaultDict[int, str | tuple[OptionParser, OptionConstructor]] - #: DefaultDict[Enum_MPTCPOption, str | tuple[MPOptionParser, MPOptionConstructor]]: Option - #: code to method mapping, c.f. :meth:`_read_mode_mp` and :meth:`_make_mode_mp`. - #: Method names are expected to be referred to the class by ``_read_mptcp_${name}`` - #: and ``_make_mptcp_${name}``, and if such name not found, the value should - #: then be a method that can parse the option by itself. + #: Option code to method mapping, see :meth:`_read_mode_mp` and + #: :meth:`_make_mode_mp`. Method names are expected to be referred to the + #: class by ``_read_mptcp_${name}`` and ``_make_mptcp_${name}``, and if such + #: name not found, the value should then be a method that can parse the + #: option by itself. __mp_option__ = collections.defaultdict( lambda: 'unknown', { diff --git a/pcapkit/protocols/transport/transport.py b/pcapkit/protocols/transport/transport.py index 029ad51e83..96f14e059c 100644 --- a/pcapkit/protocols/transport/transport.py +++ b/pcapkit/protocols/transport/transport.py @@ -43,7 +43,7 @@ class Transport(ProtocolBase[_PT, _ST], Generic[_PT, _ST]): # pylint: disable=a if TYPE_CHECKING: #: Protocol index mapping for decoding next layer, - #: c.f. :meth:`self._decode_next_layer ` + #: see :meth:`self._decode_next_layer ` #: & :meth:`self._import_next_layer `. __proto__: 'DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]' diff --git a/pcapkit/protocols/transport/udp.py b/pcapkit/protocols/transport/udp.py index 8036772a10..c4fcbefd6f 100644 --- a/pcapkit/protocols/transport/udp.py +++ b/pcapkit/protocols/transport/udp.py @@ -7,7 +7,7 @@ :mod:`pcapkit.protocols.transport.udp` contains :class:`~pcapkit.protocols.transport.udp.UDP` only, -which implements extractor for User Datagram Protocol +which implements the extractor for User Datagram Protocol (UDP) [*]_, whose structure is described as below: ======= ========= ===================== =============================== @@ -15,7 +15,7 @@ ======= ========= ===================== =============================== 0 0 ``udp.srcport`` Source Port 2 16 ``udp.dstport`` Destination Port - 4 32 ``udp.len`` Length (header includes) + 4 32 ``udp.len`` Length (header included) 6 48 ``udp.checksum`` Checksum ======= ========= ===================== =============================== @@ -85,10 +85,11 @@ class UDP(Transport[Data_UDP, Schema_UDP], # Defaults. ########################################################################## - #: DefaultDict[int, ModuleDescriptor[ProtocolBase] | ~typing.Type[ProtocolBase]]: Protocol - #: index mapping for decoding next layer, c.f. - #: :meth:`self._decode_next_layer ` - #: & :meth:`self._import_next_layer `. + #: Protocol index mapping for decoding next layer, see + #: :meth:`self._decode_next_layer + #: ` & + #: :meth:`self._import_next_layer + #: `. __proto__ = collections.defaultdict( lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'), { @@ -101,7 +102,7 @@ class UDP(Transport[Data_UDP, Schema_UDP], # # The HTTP entries bind the version-dispatching # :class:`pcapkit.protocols.application.http.HTTP`, as TCP's table - # does. c.f. the note in the class docstring. + # does. See the note in the class docstring. 80: ModuleDescriptor('pcapkit.protocols.application.http', 'HTTP'), 8080: ModuleDescriptor('pcapkit.protocols.application.http', 'HTTP'), @@ -110,7 +111,7 @@ class UDP(Transport[Data_UDP, Schema_UDP], # abstract L2TP base. IANA protocol number 115 (L2TPv3, RFC 3931) # stays unbound because that version has no class; once it has, # it takes 115 and this entry becomes a version switch on the Ver - # nibble. c.f. pcapkit.protocols.link.l2tp. + # nibble. See pcapkit.protocols.link.l2tp. 1701: ModuleDescriptor('pcapkit.protocols.link.l2tpv2', 'L2TPv2'), }, )