docs(protocols): fifth whole-repo pass over internet (#1103)

docs/source/pcapkit/protocols/internet/ah.rst

@@ -25,6 +25,7 @@ Octets      Bits        Name                    Description
    :show-inheritance:
 
    .. autoproperty:: name
+   .. autoproperty:: alias
    .. autoproperty:: length
    .. autoproperty:: payload
    .. autoproperty:: protocol

docs/source/pcapkit/protocols/internet/esp.rst

@@ -43,7 +43,9 @@ negotiated out of band. Therefore:
    :show-inheritance:
 
    .. autoproperty:: name
+   .. autoproperty:: alias
    .. autoproperty:: length
+   .. autoproperty:: protocol
 
    .. automethod:: id
 

docs/source/pcapkit/protocols/internet/internet.rst

@@ -30,6 +30,9 @@ which is a base class for internet layer protocols, e.g. :class:`~pcapkit.protoc
       :no-value:
    .. autoattribute:: _exthdr_depth
 
+.. autodata:: pcapkit.protocols.internet.internet._exthdr_rebuilt
+   :no-value:
+
 Extension Header Chains
 -----------------------
 

docs/source/pcapkit/protocols/internet/ipv6_route.rst

@@ -98,6 +98,7 @@ Auxiliary Functions
 
 .. autofunction:: pcapkit.protocols.schema.internet.ipv6_route.ipv6_route_data_selector
 .. autofunction:: pcapkit.protocols.schema.internet.ipv6_route.ipv6_route_data_length
+.. autofunction:: pcapkit.protocols.schema.internet.ipv6_route.ipv6_route_header_length
 
 Data Models
 -----------

docs/source/pcapkit/protocols/internet/mh.rst

@@ -30,6 +30,7 @@ Octets      Bits        Name                    Description
    :show-inheritance:
 
    .. autoproperty:: name
+   .. autoproperty:: alias
    .. autoproperty:: length
    .. autoproperty:: payload
    .. autoproperty:: protocol

pcapkit/protocols/data/internet/hip.py

@@ -169,9 +169,9 @@ class ESPInfoParameter(Parameter):
     reserved: 'int'
     #: KEYMAT index.
     index: 'int'
-    #: Old SDI.
+    #: Old SPI.
     old_spi: 'int'
-    #: New SDI.
+    #: New SPI.
     new_spi: 'int'
 
     if TYPE_CHECKING:
@@ -338,7 +338,7 @@ def __init__(self, type: 'Enum_Parameter', critical: 'bool', length: 'int', inde
 class SEQParameter(Parameter):
     """Data model for HIP ``SEQ`` parameter."""
 
-    #: Unique ID.
+    #: Update ID.
     id: 'int'
 
     if TYPE_CHECKING:
@@ -787,7 +787,7 @@ class RouteDstParameter(Parameter):
     reserved: 'bytes'
     #: Flags.
     flags: 'Flags'
-    #: Destination address.
+    #: Destination HITs.
     hit: 'tuple[IPv6Address, ...]'
 
     if TYPE_CHECKING:
@@ -967,7 +967,7 @@ def __init__(self, type: 'Enum_Parameter', critical: 'bool', length: 'int', rese
 class FromParameter(Parameter):
     """Data model for HIP ``FROM`` parameter."""
 
-    #: HIT address.
+    #: Address.
     address: 'IPv6Address'
 
     if TYPE_CHECKING:

pcapkit/protocols/data/internet/hopopt.py

@@ -190,7 +190,7 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class PDMOption(Option):
-    """Data model for HOPOPT Performance Diagnostic Metrics (PDM) option."""
+    """Data model for HOPOPT Performance and Diagnostic Metrics (PDM) option."""
 
     #: Scale delta time last received.
     scaledtlr: 'int'
@@ -340,7 +340,7 @@ class MPLOption(Option):
 
     """
 
-    #: Seed length.
+    #: Seed-ID type, which gives the length of the Seed-ID.
     seed_type: 'SeedID'
     #: Flags.
     flags: 'MPLFlags'

pcapkit/protocols/data/internet/ipv6_opts.py

@@ -198,7 +198,7 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class PDMOption(Option):
-    """Data model for IPv6-Opts Performance Diagnostic Metrics (PDM) option."""
+    """Data model for IPv6-Opts Performance and Diagnostic Metrics (PDM) option."""
 
     #: Scale delta time last received.
     scaledtlr: 'int'
@@ -352,7 +352,7 @@ class MPLOption(Option):
 
     """
 
-    #: Seed length.
+    #: Seed-ID type, which gives the length of the Seed-ID.
     seed_type: 'SeedID'
     #: Flags.
     flags: 'MPLFlags'

pcapkit/protocols/internet/hip.py

@@ -726,7 +726,9 @@ def register_parameter(cls, code: 'Enum_Parameter', meth: 'str | tuple[Parameter
 
         Args:
             code: HIP parameter code.
-            meth: Method name or callable to parse and/or construct the parameter.
+            meth: Name ``X`` of the ``_read_param_X`` and ``_make_param_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__parameter__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for

pcapkit/protocols/internet/hopopt.py

@@ -397,7 +397,9 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
 
         Args:
             code: HOPOPT option code.
-            meth: Method name or callable to parse and/or construct the option.
+            meth: Name ``X`` of the ``_read_opt_X`` and ``_make_opt_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__option__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1381,8 +1383,8 @@ def _make_hopopt_options(self, options: 'list[Schema_Option | tuple[Enum_Option,
         Note:
             Options given as a :obj:`list` are fresh input: padding options in
             it are dropped, and padding is inserted after each option to align
-            the header. Options given as an
-            :class:`~pcapkit.corekit.multidict.OrderedMultiDict`, i.e. parsed
+            the header. Options given as a mapping, such as the
+            :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` of parsed
             data, are emitted in order with their own padding options kept, and
             padding is added only at the end if the header is not aligned.
 

pcapkit/protocols/internet/internet.py

@@ -83,6 +83,8 @@ class Internet(ProtocolBase[_PT, _ST], Generic[_PT, _ST]):  # pylint: disable=ab
          - :class:`pcapkit.protocols.internet.mh.MH`
        * - :attr:`~pcapkit.const.reg.transtype.TransType.HIP`
          - :class:`pcapkit.protocols.internet.hip.HIP`
+       * - :attr:`~pcapkit.const.reg.transtype.TransType.Shim6`
+         - :class:`pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`
        * - :attr:`~pcapkit.const.reg.transtype.TransType.SCTP`
          - :class:`pcapkit.protocols.transport.sctp.SCTP`
        * - :attr:`~pcapkit.const.reg.transtype.TransType.OSPFIGP`

pcapkit/protocols/internet/ipv4.py

@@ -583,7 +583,9 @@ def register_option(cls, code: 'Enum_OptionNumber', meth: 'str | tuple[OptionPar
 
         Args:
             code: IPv4 option code.
-            meth: Method name or callable to parse and/or construct the option.
+            meth: Name ``X`` of the ``_read_opt_X`` and ``_make_opt_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__option__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for

pcapkit/protocols/internet/ipv6_opts.py

@@ -389,7 +389,9 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
 
         Args:
             code: IPv6-Opts option code.
-            meth: Method name or callable to parse and/or construct the option.
+            meth: Name ``X`` of the ``_read_opt_X`` and ``_make_opt_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__option__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1369,8 +1371,8 @@ def _make_ipv6_opts(self, options: 'list[Schema_Option | tuple[Enum_Option, dict
         Note:
             Options given as a :obj:`list` are fresh input: padding options in
             it are dropped, and padding is inserted after each option to align
-            the header. Options given as an
-            :class:`~pcapkit.corekit.multidict.OrderedMultiDict`, i.e. parsed
+            the header. Options given as a mapping, such as the
+            :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` of parsed
             data, are emitted in order with their own padding options kept, and
             padding is added only at the end if the header is not aligned.
 

pcapkit/protocols/internet/ipv6_route.py

@@ -386,7 +386,9 @@ def register_routing(cls, code: 'Enum_Routing', meth: 'str | tuple[TypeParser, T
 
         Args:
             code: IPv6-Route data type code.
-            meth: Method name or callable to parse and/or construct the data.
+            meth: Name ``X`` of the ``_read_data_type_X`` and
+                ``_make_data_type_X`` methods, or a ``(parser, constructor)`` pair
+                of callables, see :attr:`__routing__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for

pcapkit/protocols/internet/mh.py

@@ -1440,11 +1440,11 @@ def make(self,
             next: Next header type.
             next_default: Default value for next header type field.
             next_namespace: Namespace of next header type field.
-            next_reversed: Whether the bits of next header type field is reversed.
+            next_reversed: Whether the namespace of next header type field is reversed.
             type: Mobility Header type.
             type_default: Default value for Mobility Header type field.
             type_namespace: Namespace of Mobility Header type field.
-            type_reversed: Whether the bits of Mobility Header type field is reversed.
+            type_reversed: Whether the namespace of Mobility Header type field is reversed.
             reserved: Reserved octet after the MH type.
             chksum: Checksum.
             data: Message data.
@@ -1508,7 +1508,9 @@ def register_message(cls, code: 'Enum_Packet', meth: 'str | tuple[PacketParser,
 
         Args:
             code: MH message type code.
-            meth: Method name or callable to parse and/or construct the message.
+            meth: Name ``X`` of the ``_read_msg_X`` and ``_make_msg_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__message__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1531,7 +1533,9 @@ def register_option(cls, code: 'Enum_Option', meth: 'str | tuple[OptionParser, O
 
         Args:
             code: MH option code.
-            meth: Method name or callable to parse and/or construct the option.
+            meth: Name ``X`` of the ``_read_opt_X`` and ``_make_opt_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__option__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1554,7 +1558,9 @@ def register_extension(cls, code: 'Enum_CGAExtension', meth: 'str | tuple[Extens
 
         Args:
             code: CGA extension code.
-            meth: Method name or callable to parse and/or construct the extension.
+            meth: Name ``X`` of the ``_read_ext_X`` and ``_make_ext_X``
+                methods, or a ``(parser, constructor)`` pair of callables, see
+                :attr:`__extension__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -4544,7 +4550,7 @@ def _read_opt_ipv4_dhcp(self, schema: 'Schema_IPv4DHCPSupportModeOption', *,
         Note:
             The ``S`` bit is the **last** bit of the option, not the first -- the
             reserved field precedes it rather than following it, which is the
-            other way round from every other flag in this module.
+            other way round from most flags in this module.
 
         Args:
             schema: Parsed option schema.
@@ -5433,8 +5439,11 @@ def _read_opt_mcast_sel(self, schema: 'Schema_DynamicIPMulticastSelectorOption',
             :rfc:`3376#section-4.2` IGMP structures. They belong to those protocols
             rather than to the mobility header, and each is self-describing through
             its own auxiliary-data length and source count, so they are recorded
-            opaquely here rather than half-decoded. :attr:`protocol` says which of
-            the two they are: ``143`` for MLDv2, ``131`` for MLDv1.
+            opaquely here rather than half-decoded.
+            :attr:`~pcapkit.protocols.data.internet.mh.DynamicIPMulticastSelectorOption.protocol`
+            says which of the two they are: ``143`` for MLDv2 and ``131`` for MLDv1,
+            or ``0x12``, ``0x16`` and ``0x22`` for IGMPv1 to IGMPv3
+            [:rfc:`7028#section-8`].
 
         Args:
             schema: Parsed option schema.

pcapkit/protocols/schema/internet/hip.py

@@ -620,6 +620,7 @@ class Locator(Schema):
             'preferred': (7, 1),
         },
     )
+    #: Locator lifetime, in seconds.
     lifetime: 'int' = UInt32Field()
     #: Locator value.
     value: 'IPv6Address | LocatorData' = SwitchField(

pcapkit/protocols/schema/internet/ipv6_route.py

@@ -82,9 +82,11 @@ def ipv6_route_header_length(hdr_ext_len: 'int') -> 'int':
     route data's own ``.length``, which
     :meth:`~pcapkit.protocols.internet.ipv6_route.IPv6_Route.read` then
     subtracts from the outer packet length to find the next layer's length.
-    It is the read-side counterpart of
-    :meth:`~pcapkit.protocols.internet.ipv6_route.IPv6_Route._make_hdr_ext_len`,
-    which does the inverse arithmetic on the write side.
+    Its inverse is the ``(length - 8) // 8`` that
+    :meth:`~pcapkit.protocols.internet.ipv6_route.IPv6_Route._make_data`
+    passes back as ``hdr_ext_len``;
+    :meth:`~pcapkit.protocols.internet.ipv6_route.IPv6_Route._make_hdr_ext_len`
+    inverts :func:`ipv6_route_data_length` instead.
 
     Args:
         hdr_ext_len: raw ``Hdr Ext Len`` field value, as read off the wire.