From 2cf6a3e100eb182152c3fa4973e1ca9e5e998aff Mon Sep 17 00:00:00 2001
From: Jarry Shaw <jarryshaw@icloud.com>
Date: Sun, 25 Oct 2026 00:47:33 -0400
Subject: [PATCH] docs(protocols): fifth whole-repo pass over internet (#1103)

- register_* docs: describe ``meth`` as a method-name suffix or a
  (parser, constructor) pair, matching the registry dispatch
- Internet ``__proto__`` table: add the missing Shim6 row
- HIP/HOPOPT/IPv6-Opts/MH field comments: fix SPI, Update ID,
  Destination HITs, PDM and Seed-ID wording; document Locator lifetime
- HOPOPT/IPv6-Opts ``_make_*_options``: OrderedMultiInfo, not
  OrderedMultiDict (#1484)
- MH: reversed-namespace flags, IGMP selector protocol values
- IPv6-Route: name the inverse of ipv6_route_header_length
- rst: add missing alias/protocol, _exthdr_rebuilt and
  ipv6_route_header_length directives

Prose only; AST identical with docstrings stripped.
---
 docs/source/pcapkit/protocols/internet/ah.rst |  1 +
 .../source/pcapkit/protocols/internet/esp.rst |  2 ++
 .../pcapkit/protocols/internet/internet.rst   |  3 +++
 .../pcapkit/protocols/internet/ipv6_route.rst |  1 +
 docs/source/pcapkit/protocols/internet/mh.rst |  1 +
 pcapkit/protocols/data/internet/hip.py        | 10 ++++----
 pcapkit/protocols/data/internet/hopopt.py     |  4 +--
 pcapkit/protocols/data/internet/ipv6_opts.py  |  4 +--
 pcapkit/protocols/internet/hip.py             |  4 ++-
 pcapkit/protocols/internet/hopopt.py          |  8 +++---
 pcapkit/protocols/internet/internet.py        |  2 ++
 pcapkit/protocols/internet/ipv4.py            |  4 ++-
 pcapkit/protocols/internet/ipv6_opts.py       |  8 +++---
 pcapkit/protocols/internet/ipv6_route.py      |  4 ++-
 pcapkit/protocols/internet/mh.py              | 25 +++++++++++++------
 pcapkit/protocols/schema/internet/hip.py      |  1 +
 .../protocols/schema/internet/ipv6_route.py   |  8 +++---
 17 files changed, 61 insertions(+), 29 deletions(-)

diff --git a/docs/source/pcapkit/protocols/internet/ah.rst b/docs/source/pcapkit/protocols/internet/ah.rst
index 473226b10f..cbda33ca33 100644
--- a/docs/source/pcapkit/protocols/internet/ah.rst
+++ b/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
diff --git a/docs/source/pcapkit/protocols/internet/esp.rst b/docs/source/pcapkit/protocols/internet/esp.rst
index 910d5d607b..83d3c92ec8 100644
--- a/docs/source/pcapkit/protocols/internet/esp.rst
+++ b/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
 
diff --git a/docs/source/pcapkit/protocols/internet/internet.rst b/docs/source/pcapkit/protocols/internet/internet.rst
index d9eac23a59..c49cbf69d6 100644
--- a/docs/source/pcapkit/protocols/internet/internet.rst
+++ b/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
 -----------------------
 
diff --git a/docs/source/pcapkit/protocols/internet/ipv6_route.rst b/docs/source/pcapkit/protocols/internet/ipv6_route.rst
index 8f3162e131..f1e24199b9 100644
--- a/docs/source/pcapkit/protocols/internet/ipv6_route.rst
+++ b/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
 -----------
diff --git a/docs/source/pcapkit/protocols/internet/mh.rst b/docs/source/pcapkit/protocols/internet/mh.rst
index 0654f1214b..c5169f92cb 100644
--- a/docs/source/pcapkit/protocols/internet/mh.rst
+++ b/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
diff --git a/pcapkit/protocols/data/internet/hip.py b/pcapkit/protocols/data/internet/hip.py
index 819d6df77f..25f33a946a 100644
--- a/pcapkit/protocols/data/internet/hip.py
+++ b/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:
diff --git a/pcapkit/protocols/data/internet/hopopt.py b/pcapkit/protocols/data/internet/hopopt.py
index 8c51ee2b72..8d49872038 100644
--- a/pcapkit/protocols/data/internet/hopopt.py
+++ b/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'
diff --git a/pcapkit/protocols/data/internet/ipv6_opts.py b/pcapkit/protocols/data/internet/ipv6_opts.py
index 0fc63bac5e..1b4d134245 100644
--- a/pcapkit/protocols/data/internet/ipv6_opts.py
+++ b/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'
diff --git a/pcapkit/protocols/internet/hip.py b/pcapkit/protocols/internet/hip.py
index 83d480545f..bfed69e20f 100644
--- a/pcapkit/protocols/internet/hip.py
+++ b/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
diff --git a/pcapkit/protocols/internet/hopopt.py b/pcapkit/protocols/internet/hopopt.py
index c933c386b8..15b925713f 100644
--- a/pcapkit/protocols/internet/hopopt.py
+++ b/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.
 
diff --git a/pcapkit/protocols/internet/internet.py b/pcapkit/protocols/internet/internet.py
index 100204055f..69bfc4ceb3 100644
--- a/pcapkit/protocols/internet/internet.py
+++ b/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`
diff --git a/pcapkit/protocols/internet/ipv4.py b/pcapkit/protocols/internet/ipv4.py
index d9ff253297..bcea06b05b 100644
--- a/pcapkit/protocols/internet/ipv4.py
+++ b/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
diff --git a/pcapkit/protocols/internet/ipv6_opts.py b/pcapkit/protocols/internet/ipv6_opts.py
index 60f7609c21..65145624ba 100644
--- a/pcapkit/protocols/internet/ipv6_opts.py
+++ b/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.
 
diff --git a/pcapkit/protocols/internet/ipv6_route.py b/pcapkit/protocols/internet/ipv6_route.py
index 70e6a6100a..3995614177 100644
--- a/pcapkit/protocols/internet/ipv6_route.py
+++ b/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
diff --git a/pcapkit/protocols/internet/mh.py b/pcapkit/protocols/internet/mh.py
index f5086ab4f6..a78f0f1cf9 100644
--- a/pcapkit/protocols/internet/mh.py
+++ b/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.
diff --git a/pcapkit/protocols/schema/internet/hip.py b/pcapkit/protocols/schema/internet/hip.py
index b2704ed6ca..cb7d61cf78 100644
--- a/pcapkit/protocols/schema/internet/hip.py
+++ b/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(
diff --git a/pcapkit/protocols/schema/internet/ipv6_route.py b/pcapkit/protocols/schema/internet/ipv6_route.py
index 9f96260383..3dd0afede2 100644
--- a/pcapkit/protocols/schema/internet/ipv6_route.py
+++ b/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.