docs(protocols): fourth whole-repo pass over link and transport protocols (#1103)

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``.
 

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:
 

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 <pcapkit.protocols.application.httpv1.HTTP.id>` for
+QUIC. See :meth:`HTTPv1.id <pcapkit.protocols.application.httpv1.HTTP.id>` for
 how a version-flavoured alias is spelled: canonical name first, alias second,
 since callers take element zero as canonical.
 

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

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:
 

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

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:
 

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:
 

docs/source/pcapkit/protocols/transport/udp.rst

@@ -5,15 +5,15 @@ 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:
 
 ======= ========= ===================== ===============================
 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
 ======= ========= ===================== ===============================
 

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.

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.

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:
 

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 <pcapkit.protocols.application.httpv1.HTTP.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 <pcapkit.protocols.link.l2tpv2.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
 

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

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 <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
-    #: & :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`.
+    #: Protocol index mapping for decoding next layer, see
+    #: :meth:`self._decode_next_layer
+    #: <pcapkit.protocols.protocol.Protocol._decode_next_layer>` &
+    #: :meth:`self._import_next_layer
+    #: <pcapkit.protocols.protocol.Protocol._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]]

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 <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
-    #: & :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._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
+    #: <pcapkit.protocols.protocol.Protocol._decode_next_layer>` &
+    #: :meth:`self._import_next_layer
+    #: <pcapkit.protocols.protocol.Protocol._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__
     #: <pcapkit.protocols.link.link.Link.__proto__>`.
     __proto__ = collections.defaultdict(
         lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'),

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 <pcapkit.protocols.link.c_tag.C_Tag.info_name>`
+    #: NOTE: see :attr:`C_Tag.info_name <pcapkit.protocols.link.c_tag.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

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 <pcapkit.protocols.schema.internet.ipv4.IPv4.trailer>`.
     #: Always empty when the ``L`` flag is clear, since the payload then takes
     #: the rest of the datagram.

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 <pcapkit.protocols.schema.internet.ipv4.IPv4.trailer>`.
     trailer: 'bytes' = PayloadField(default=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,

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 <pcapkit.protocols.schema.internet.ipv4.IPv4.trailer>`.
     trailer: 'bytes' = PayloadField(default=b'')