docs(protocols): second pass over link and transport (#1103)

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

@@ -18,16 +18,17 @@ modules of their own:
    * - ``0x88A8`` (service tag, 802.1ad)
      - :class:`~pcapkit.protocols.link.s_tag.S_Tag`
 
-The tag structure is described as below:
+The tag structure is described as below, keyed as for a customer tag; a service
+tag's keys start ``s_tag`` instead:
 
 ======= ========= ====================== =============================
 Octets      Bits        Name                    Description
 ======= ========= ====================== =============================
-  0           0   ``vlan.tci``              Tag Control Information
-  0           0   ``vlan.tci.pcp``          Priority Code Point
-  0           3   ``vlan.tci.dei``          Drop Eligible Indicator
-  0           4   ``vlan.tci.vid``          VLAN Identifier
-  2          16   ``vlan.type``             Protocol (Internet Layer)
+  0           0   ``c_tag.tci``             Tag Control Information
+  0           0   ``c_tag.tci.pcp``         Priority Code Point
+  0           3   ``c_tag.tci.dei``         Drop Eligible Indicator
+  0           4   ``c_tag.tci.vid``         VLAN Identifier
+  2          16   ``c_tag.type``            Protocol (Internet Layer)
 ======= ========= ====================== =============================
 
 The two tags carry an identical tag control information layout and differ only

pcapkit/protocols/data/link/l2tp.py

@@ -17,7 +17,7 @@
 
 @info_final
 class Flags(Data):
-    """Data model for L2TP flags and version info."""
+    """Data model for L2TP flags."""
 
     #: Type.
     type: 'Type'
@@ -43,7 +43,7 @@ def __init__(self, type: 'Type', len: 'bool', seq: 'bool', offset: 'bool', prio:
 class L2TP(Protocol):
     """Data model for L2TP packet."""
 
-    #: Flags and version info.
+    #: Flags; the version nibble is :attr:`version`.
     flags: 'Flags'
     #: Version.
     version: 'int'

pcapkit/protocols/data/transport/tcp.py

@@ -86,7 +86,7 @@ class TCP(Protocol):
     seq: 'int'
     #: Acknowledgment number.
     ack: 'int'
-    #: Data offset.
+    #: Header length, i.e. the Data Offset in octets.
     hdr_len: 'int'
     #: Flags.
     flags: 'Flags'
@@ -225,9 +225,9 @@ def __init__(self, kind: 'OptionNumber', length: 'int', data: 'bytes') -> 'None'
 class Timestamps(Option):
     """Data model for TCP timestamp option."""
 
-    #: Timestamp .
+    #: Timestamp value.
     timestamp: 'int'
-    #: Echo data.
+    #: Timestamp echo reply.
     echo: 'int'
 
     if TYPE_CHECKING:
@@ -244,7 +244,7 @@ def __init__(self, kind: 'OptionNumber', length: 'int') -> 'None': ...  # pylint
 
 @info_final
 class PartialOrderServiceProfile(Option):
-    """Data model for TCP partial order connection profile option."""
+    """Data model for TCP partial order connection service profile option."""
 
     #: Start flag.
     start: 'bool'
@@ -403,15 +403,16 @@ def __init__(self, kind: 'OptionNumber', length: 'int', subtype: 'MPTCPOption',
 class MPTCPCapableFlag(Data):
     """Data model for TCP MPTCP capable option flags."""
 
-    #: Checksum require flag.
+    #: Checksum required flag.
     req: 'bool'
     #: Extensibility flag.
     ext: 'bool'
     #: Flag for not establishing new subflows to the source address (``C``).
     deny_join: 'bool'
     #: Reserved flags (``D`` to ``G``).
     reserved: 'int'
-    #: HMAC-SHA1 flag.
+    #: HMAC algorithm flag (``H``): HMAC-SHA1 under version 0 (:rfc:`6824`),
+    #: HMAC-SHA256 under version 1 (:rfc:`8684`).
     hsa: 'bool'
 
     if TYPE_CHECKING:

pcapkit/protocols/data/transport/udp.py

@@ -20,7 +20,7 @@ class UDP(Protocol):
     srcport: 'AppType'
     #: Destination port.
     dstport: 'AppType'
-    #: Length (header includes).
+    #: Length, header included.
     len: 'int'
     #: Checksum.
     checksum: 'bytes'

pcapkit/protocols/link/vlan.py

@@ -10,16 +10,17 @@
 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
-service tag (``0x88A8``). The tag structure is described as below:
+service tag (``0x88A8``). The tag structure is described as below, keyed as for
+a customer tag; a service tag's keys start ``s_tag`` instead:
 
 ======= ========= ====================== =============================
 Octets      Bits        Name                    Description
 ======= ========= ====================== =============================
-  0           0   ``vlan.tci``              Tag Control Information
-  0           0   ``vlan.tci.pcp``          Priority Code Point
-  0           3   ``vlan.tci.dei``          Drop Eligible Indicator
-  0           4   ``vlan.tci.vid``          VLAN Identifier
-  2          16   ``vlan.type``             Protocol (Internet Layer)
+  0           0   ``c_tag.tci``             Tag Control Information
+  0           0   ``c_tag.tci.pcp``         Priority Code Point
+  0           3   ``c_tag.tci.dei``         Drop Eligible Indicator
+  0           4   ``c_tag.tci.vid``         VLAN Identifier
+  2          16   ``c_tag.type``            Protocol (Internet Layer)
 ======= ========= ====================== =============================
 
 The two tags carry an **identical** tag control information layout -- the same

pcapkit/protocols/schema/transport/tcp.py

@@ -164,7 +164,7 @@ class MPTCPCapableFlags(TypedDict):
         deny_join: int
         #: Reserved flags (``D`` to ``G``).
         reserved: int
-        #: Use of HMAC-SHA1.
+        #: Use of HMAC-SHA1 under version 0, HMAC-SHA256 under version 1.
         hsa: int
 
     class MPTCPSubtypeJoin(TypedDict):
@@ -679,7 +679,8 @@ class _MPTCP(Schema):
     #: Subtype and flags.
     #:
     #: The forward match is anchored at the option's first octet, not after the
-    #: option header: this schema is what :data:`Option.registry` dispatches to
+    #: option header: this schema is what :attr:`Option.registry
+    #: <pcapkit.protocols.schema.schema.EnumSchema.registry>` dispatches to
     #: for ``kind == Multipath_TCP`` and, unlike the other option schemas, it
     #: does not inherit :class:`Option` and so consumes ``kind`` and ``length``
     #: itself. :rfc:`8684` section 3 therefore puts ``kind`` in bits 0-7,

pcapkit/protocols/transport/tcp.py

@@ -304,7 +304,8 @@ class TCP(Transport[Data_TCP, Schema_TCP],
 
     .. versionchanged:: 1.5.0
 
-       * :meth:`read` reports the flags of a flagless segment as an empty
+       * :meth:`read` reports the :attr:`connection` flags of a flagless
+         segment, and ``info.connection``, as an empty
          :class:`~pcapkit.const.tcp.flags.Flags` rather than a plain
          :obj:`int` (:issue:`616`).
        * A constructed MPTCP option sets its ``subtype`` (:issue:`566`), and
@@ -2893,7 +2894,8 @@ def _make_mptcp_capable(self, subtype: 'Enum_MPTCPOption', opt: 'Optional[Data_M
             flag_deny_join: flag for not establishing new subflows to the
                 source address
             flag_reserved: reserved flags (``D`` to ``G``)
-            flag_hsa: use of HMAC-SHA1 flag
+            flag_hsa: use of HMAC-SHA1 (version 0) or HMAC-SHA256
+                (version 1) flag
             skey: option sender's key
             rkey: option receiver's key
             dl_len: data-level length