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

docs/source/pcapkit/protocols/link/vlan.rst

@@ -5,7 +5,7 @@ VLAN - 802.1Q/802.1ad VLAN Tag Types
 
 :mod:`pcapkit.protocols.link.vlan` contains
 :class:`~pcapkit.protocols.link.vlan.VLAN` only, an abstract base class holding
-the tag layout shared by every VLAN tag [*]_. The two concrete tags live in
+the tag layout shared by every VLAN tag [*]_. The concrete tags live in
 modules of their own:
 
 .. list-table::

pcapkit/protocols/link/arp.py

@@ -418,9 +418,10 @@ def _make_addr_resolve(self, addr: 'str | bytes', htype: 'int') -> 'bytes':
 
         """
         # NOTE: checked before the ``htype`` dispatch, for the same reason as
-        # in ``_make_proto_resolve``: without it a ``bool`` reaches the MAC
-        # pattern or falls through unchanged, and fails later as a
-        # ``TypeError`` (#2166).
+        # in ``_make_proto_resolve``: without it a ``bool`` gets the generic
+        # ``ProtocolError`` the branches below raise for any non-address,
+        # rather than the ``FieldValueError`` ``_make_proto_resolve`` raises
+        # for one (#2166).
         if isinstance(addr, bool):
             raise FieldValueError(
                 f'{self.__class__.__name__}: invalid hardware address: must not be a bool, '
@@ -492,8 +493,8 @@ def _make_proto_resolve(self, addr: 'IPv4Address | IPv6Address | str | bytes', p
         # NOTE: checked before the ``ptype`` dispatch, for the placement reason
         # ``_reject_bool`` in ``pcapkit.corekit.fields.ipaddress`` gives: the
         # non-IP branches below never reach ``parse_ip_address``, so without it
-        # a ``bool`` falls through them unchanged and fails later as a
-        # ``TypeError`` from ``len()`` (#2166).
+        # a ``bool`` gets their generic ``ProtocolError`` rather than the
+        # ``FieldValueError`` the IP branches raise for it (#2166).
         if isinstance(addr, bool):
             raise FieldValueError(
                 f'{self.__class__.__name__}: invalid protocol address: must not be a bool, '

pcapkit/protocols/link/l2tpv2.py

@@ -429,8 +429,8 @@ def _make_data(cls, data: 'Data_L2TP') -> 'dict[str, Any]':  # type: ignore[over
             'version': data.version,
             # NOTE: Passed as ``total_length`` since ``length`` is the parse
             # length :class:`~pcapkit.protocols.protocol.ProtocolBase` takes, so
-            # under that key it never reached :meth:`make`, and the rebuild
-            # dropped both the Length field and the ``L`` flag (#1172).
+            # under that key it would never reach :meth:`make`, and the rebuild
+            # would drop both the Length field and the ``L`` flag (#1172).
             'total_length': data.length,
             # NOTE: Passed so that a control message captured without ``L``
             # rebuilds as captured, rather than gaining the Length field

pcapkit/protocols/link/vlan.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.link.vlan` contains
 :class:`~pcapkit.protocols.link.vlan.VLAN` only, an abstract base class holding
-the tag layout shared by every VLAN tag [*]_. The two concrete tags live in
+the tag layout shared by every VLAN tag [*]_. The concrete tags live in
 modules of their own, since they are reached through different registry indices
 -- :class:`~pcapkit.protocols.link.c_tag.C_Tag` for the 802.1Q customer tag
 (``0x8100``) and :class:`~pcapkit.protocols.link.s_tag.S_Tag` for the 802.1ad
@@ -39,7 +39,7 @@
 would nest one ``c_tag`` inside another, leaving nothing in the output to say
 which of the two was the service tag.
 
-Two distinct EtherTypes also means two distinct
+Two distinct EtherTypes also mean two distinct
 :meth:`~pcapkit.protocols.protocol.Protocol.__index__` values, which is the
 project's rule for when protocols get separate modules: siblings that *share* an
 index may share a module, as :class:`~pcapkit.protocols.link.arp.InARP` shares