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

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

@@ -15,7 +15,7 @@ Octets      Bits        Name                    Description
   0           0   ``esp.spi``             Security Parameters Index (SPI)
   4          32   ``esp.seq``             Sequence Number
   8          64   ``esp.payload_data``    Payload Data (variable, encrypted)
-  ?           ?                           Padding (0-255 bytes, encrypted)
+  ?           ?   ``esp.padding``         Padding (0-255 bytes, encrypted)
   ?           ?   ``esp.pad_len``         Pad Length (encrypted)
   ?           ?   ``esp.next``            Next Header (encrypted)
   ?           ?   ``esp.icv``             Integrity Check Value (ICV, variable)
@@ -217,8 +217,10 @@ MD5, DES-MAC, KPDK-MD5       MUST NOT            **no**       registered, delibe
    :show-inheritance:
 
 .. autodata:: pcapkit.protocols.internet.esp.CIPHER_SUITES
+   :no-value:
 
 .. autodata:: pcapkit.protocols.internet.esp.INTEGRITY_SUITES
+   :no-value:
 
 Known Limitations
 -----------------

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

@@ -4,9 +4,9 @@ Base Protocol
 .. module:: pcapkit.protocols.internet.internet
 
 :mod:`pcapkit.protocols.internet.internet` contains :class:`~pcapkit.protocols.internet.internet.Internet`,
-which is a base class for internet layer protocols, eg. :class:`~pcapkit.protocols.internet.ah.AH`,
+which is a base class for internet layer protocols, e.g. :class:`~pcapkit.protocols.internet.ah.AH`,
 :class:`~pcapkit.protocols.internet.ipsec.IPsec`, :class:`~pcapkit.protocols.internet.ipv4.IPv4`,
-:class:`~pcapkit.protocols.internet.ipv6.IPv6`, :class:`~pcapkit.protocols.internet.ipx.IPX`, and etc.
+:class:`~pcapkit.protocols.internet.ipv6.IPv6` and :class:`~pcapkit.protocols.internet.ipx.IPX`.
 
 .. autoclass:: pcapkit.protocols.internet.internet.Internet
    :no-members:
@@ -40,7 +40,7 @@ kept as :class:`~pcapkit.protocols.misc.raw.Raw`, with one
 :exc:`~pcapkit.utilities.warnings.ProtocolWarning` (:issue:`1604`). The
 ``pyshark`` engine leaves the walk to its own parser, which does not stop there,
 so it may still find the upper layer past it (:issue:`1609`). So may the
-``dpkt`` toolkit, which reads the chain as :mod:`dpkt` decodes it. So does the
+``dpkt`` toolkit, which reads the chain as ``dpkt`` decodes it. So does the
 ``scapy`` engine behind IPv6, where Scapy dissects each extension header itself;
 behind IPv4, its toolkit steps over them in the octets to find TCP, up to
 :data:`~pcapkit.utilities.config.EXTENSION_HEADER_LIMIT` of them in a row. The

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

@@ -6,7 +6,7 @@ IP - Internet Protocol
 :mod:`pcapkit.protocols.internet.ip` contains
 :class:`~pcapkit.protocols.internet.ip.IP` only,
 which is a base class for Internet Protocol (IP)
-protocol family [*]_, eg.
+protocol family [*]_, e.g.
 :class:`~pcapkit.protocols.internet.ipv4.IPv4` and
 :class:`~pcapkit.protocols.internet.ipv6.IPv6`.
 

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

@@ -6,7 +6,7 @@ IPsec - Internet Protocol Security
 :mod:`pcapkit.protocols.internet.ipsec` contains
 :class:`~pcapkit.protocols.internet.ipsec.IPsec`
 only, which is a base class for Internet Protocol
-Security (IPsec) protocol family [*]_, eg.
+Security (IPsec) protocol family [*]_, e.g.
 :class:`~pcapkit.protocols.internet.ah.AH` and
 :class:`~pcapkit.protocols.internet.esp.ESP`.
 

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

@@ -9,9 +9,9 @@ which implements extractor for Internet Protocol
 version 4 (IPv4) [*]_, whose structure is described
 as below:
 
-======= ========= ====================== =============================================
+======= ========= ======================= ============================================
 Octets      Bits        Name                    Description
-======= ========= ====================== =============================================
+======= ========= ======================= ============================================
   0           0   ``ipv4.version``        Version (``4``)
   0           4   ``ipv4.hdr_len``        Internet Header Length (IHL)
   1           8   ``ipv4.tos.pre``        Precedence
@@ -21,7 +21,7 @@ Octets      Bits        Name                    Description
   1          14   ``ipv4.tos.ecn``        Explicit Congestion Notification (ECN)
   2          16   ``ipv4.len``            Total Length
   4          32   ``ipv4.id``             Identification
-  6          48                           Reserved Bit (must be ``\x00``)
+  6          48   ``ipv4.flags.reserved`` Reserved Bit (must be ``0``)
   6          49   ``ipv4.flags.df``       Don't Fragment (DF)
   6          50   ``ipv4.flags.mf``       More Fragments (MF)
   6          51   ``ipv4.offset``         Fragment Offset
@@ -31,7 +31,7 @@ Octets      Bits        Name                    Description
   12         96   ``ipv4.src``            Source IP Address
   16        128   ``ipv4.dst``            Destination IP Address
   20        160   ``ipv4.options``        IP Options (if IHL > ``5``)
-======= ========= ====================== =============================================
+======= ========= ======================= ============================================
 
 .. autoclass:: pcapkit.protocols.internet.ipv4.IPv4
    :no-members:
@@ -235,8 +235,8 @@ Data Models
 
       .. note::
 
-         This field is conflict with :keyword:`del` keyword. To access this field,
-         directly use :func:`getattr` instead.
+         This field's name conflicts with the :keyword:`del` keyword, so
+         access it with :func:`getattr` instead.
 
 .. autoclass:: pcapkit.protocols.data.internet.ipv4.Flags
    :members:
@@ -257,8 +257,8 @@ Data Models
 
       .. note::
 
-         This field is conflict with :keyword:`class` keyword. To access this field,
-         directly use :func:`getattr` instead.
+         This field's name conflicts with the :keyword:`class` keyword, so
+         access it with :func:`getattr` instead.
 
 .. autoclass:: pcapkit.protocols.data.internet.ipv4.UnassignedOption
    :members:
@@ -319,8 +319,8 @@ Data Models
 
       .. note::
 
-         This field is conflict with :keyword:`return` keyword. To access this field,
-         directly use :func:`getattr` instead.
+         This field's name conflicts with the :keyword:`return` keyword, so
+         access it with :func:`getattr` instead.
 
 .. autoclass:: pcapkit.protocols.data.internet.ipv4.RTRALTOption
    :members:

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

@@ -15,7 +15,7 @@ Octets      Bits        Name                    Description
   0           0   ``ipv6.version``            Version (``6``)
   0           4   ``ipv6.class``              Traffic Class
   1          12   ``ipv6.label``              Flow Label
-  4          32   ``ipv6.payload``            Payload Length (header excludes)
+  4          32   ``ipv6.payload``            Payload Length (header excluded)
   6          48   ``ipv6.next``               Next Header
   7          56   ``ipv6.limit``              Hop Limit
   8          64   ``ipv6.src``                Source Address
@@ -110,8 +110,8 @@ Data Models
 
       .. note::
 
-         This field is conflict with :keyword:`class` keyword. To access this field,
-         directly use :func:`getattr` instead.
+         This field's name conflicts with the :keyword:`class` keyword, so
+         access it with :func:`getattr` instead.
 
 .. rubric:: Footnotes
 

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

@@ -5,8 +5,8 @@ IPv6_Ext - IPv6 Extension Header
 
 :mod:`pcapkit.protocols.internet.ipv6_ext` contains
 :class:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext`
-only, which serves two roles at once. It is the shared **base class** of all
-eight IPv6 extension headers this package implements, supplying the
+only, which plays a double role. It is the shared **base class** of every
+IPv6 extension header this package implements, supplying the
 ``extension``-mode contract: the guards that make
 :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.payload`,
 :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol` and
@@ -22,7 +22,7 @@ Octets      Bits        Name                    Description
 ======= ========= ===================== =====================================
   0           0   ``next``                    Next Header
   1           8   ``len``                     Hdr Ext Len (8-octet units,
-                                                excluding the first 8 octets)
+                                              excluding the first 8 octets)
   2          16   ``payload``                 Header-specific content
 ======= ========= ===================== =====================================
 
@@ -31,7 +31,7 @@ header. The module docstring in :file:`pcapkit/protocols/internet/ipv6_ext.py`
 holds the closed exception table (``IPv6-Frag`` and ``AH`` each use their own
 length rule; ``ESP`` has a dedicated parser whose own info reports no next header
 rather than lacking one, and ``253`` and ``254`` have no dedicated parser at all,
-so none of the three ever reaches this class), the two ways this class is
+so none of them ever reaches this class), the ways this class is
 dispatched to, and why an overrun stops the walk instead of clipping it.
 
 .. autoclass:: pcapkit.protocols.internet.ipv6_ext.IPv6_Ext

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

@@ -13,7 +13,7 @@ as below:
 Octets      Bits        Name                    Description
 ======= ========= ====================== =====================================
   0           0   ``ipx.chksum``            Checksum
-  2          16   ``ipx.len``               Packet Length (header includes)
+  2          16   ``ipx.len``               Packet Length (header included)
   4          32   ``ipx.count``             Transport Control (hop count)
   5          40   ``ipx.type``              Packet Type
   6          48   ``ipx.dst``               Destination Address

pcapkit/protocols/data/internet/esp.py

@@ -23,8 +23,8 @@ class ESP(Protocol):
     :attr:`plaintext` are recovered from the *decrypted* payload, and are
     therefore :data:`None` whenever the payload could not be decrypted --
     :rfc:`4303` places them inside the ciphertext, so guessing them from an
-    encrypted payload is not possible. :attr:`status` says which of those
-    two cases applies, and :attr:`error` says why.
+    encrypted payload is not possible. :attr:`status` says which case
+    applies, and :attr:`error` says why.
 
     Important:
         No key material is recorded here, by design. This data model is what

pcapkit/protocols/data/internet/hip.py

@@ -103,7 +103,9 @@ class HIP(Protocol):
     .. versionchanged:: 1.5.0
 
        New required fields ``packet_fixed``, ``reserved`` and ``version_fixed``
-       (:issue:`1417`, :issue:`1459`).
+       (:issue:`1417`, :issue:`1459`), and ``parameters`` is an immutable
+       :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` rather than an
+       :class:`~pcapkit.corekit.multidict.OrderedMultiDict` (:issue:`1484`).
 
     """
 
@@ -256,7 +258,8 @@ class PuzzleParameter(Parameter):
     .. versionchanged:: 1.5.0
 
        New required fields ``lifetime_exponent`` and ``rhash_len``
-       (:issue:`653`, :issue:`1323`).
+       (:issue:`653`, :issue:`1323`), and ``lifetime`` is :obj:`None` past
+       :attr:`datetime.timedelta.max` (:issue:`1323`).
 
     """
 

pcapkit/protocols/data/internet/hopopt.py

@@ -53,7 +53,15 @@ class Option(Data):
 
 @info_final
 class HOPOPT(Protocol):
-    """Data model for HOPOPT protocol."""
+    """Data model for HOPOPT protocol.
+
+    .. versionchanged:: 1.5.0
+
+       ``options`` is an immutable
+       :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` rather than an
+       :class:`~pcapkit.corekit.multidict.OrderedMultiDict` (:issue:`1484`).
+
+    """
 
     #: Next header.
     next: 'TransType'
@@ -323,7 +331,14 @@ def __init__(self, max: 'bool', drop: 'bool', reserved: 'int') -> 'None': ...  #
 
 @info_final
 class MPLOption(Option):
-    """Data model for HOPOPT Multicast Protocol for Low-Power and Lossy Networks (MPL) option."""
+    """Data model for HOPOPT Multicast Protocol for Low-Power and Lossy Networks (MPL) option.
+
+    .. versionchanged:: 1.5.0
+
+       ``seed_id`` may be an :class:`~ipaddress.IPv6Address`, the source
+       address, for a seed-id type of ``IPV6_SOURCE_ADDRESS`` (:issue:`1185`).
+
+    """
 
     #: Seed length.
     seed_type: 'SeedID'

pcapkit/protocols/data/internet/ipv4.py

@@ -100,13 +100,21 @@ def __init__(self, reserved: 'int', df: 'bool', mf: 'bool') -> 'None': ...  # py
 
 @info_final
 class IPv4(Protocol):
-    """Data model for IPv4 packet."""
+    """Data model for IPv4 packet.
+
+    .. versionchanged:: 1.5.0
+
+       ``options`` is an immutable
+       :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` rather than an
+       :class:`~pcapkit.corekit.multidict.OrderedMultiDict` (:issue:`1484`).
+
+    """
 
     #: Version.
     version: 'Literal[4]'
     #: Internet header length.
     hdr_len: 'int'
-    #: Type of services.
+    #: Type of service.
     tos: 'ToSField'
     #: Total length.
     len: 'int'
@@ -247,7 +255,10 @@ class TSOption(Option):
     .. versionchanged:: 1.5.0
 
        New required fields ``remaining`` and ``remainder`` (:issue:`1349`,
-       :issue:`1392`).
+       :issue:`1392`), and a ``timestamp`` that carries addresses is an
+       immutable :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` rather
+       than an :class:`~pcapkit.corekit.multidict.OrderedMultiDict`
+       (:issue:`1484`).
 
     """
 

pcapkit/protocols/data/internet/ipv6_opts.py

@@ -53,7 +53,15 @@ class Option(Data):
 
 @info_final
 class IPv6_Opts(Protocol):
-    """Data model for IPv6-Opts protocol."""
+    """Data model for IPv6-Opts protocol.
+
+    .. versionchanged:: 1.5.0
+
+       ``options`` is an immutable
+       :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` rather than an
+       :class:`~pcapkit.corekit.multidict.OrderedMultiDict` (:issue:`1484`).
+
+    """
 
     #: Next header.
     next: 'TransType'
@@ -335,7 +343,14 @@ def __init__(self, max: 'bool', drop: 'bool', reserved: 'int') -> 'None': ...  #
 
 @info_final
 class MPLOption(Option):
-    """Data model for IPv6-Opts Multicast Protocol for Low-Power and Lossy Networks (MPL) option."""
+    """Data model for IPv6-Opts Multicast Protocol for Low-Power and Lossy Networks (MPL) option.
+
+    .. versionchanged:: 1.5.0
+
+       ``seed_id`` may be an :class:`~ipaddress.IPv6Address`, the source
+       address, for a seed-id type of ``IPV6_SOURCE_ADDRESS`` (:issue:`1185`).
+
+    """
 
     #: Seed length.
     seed_type: 'SeedID'

pcapkit/protocols/data/internet/ipx.py

@@ -26,7 +26,7 @@ class Address(Data):
     network: 'str'
     #: Node number (``-`` separated).
     node: 'str'
-    #: Socket number (``:`` separated).
+    #: Socket number.
     socket: 'Socket'
     #: Full address (``:`` separated).
     addr: 'str'
@@ -41,7 +41,7 @@ class IPX(Protocol):
 
     #: Checksum.
     chksum: 'bytes'
-    #: Packet length (header includes).
+    #: Packet length (header included).
     len: 'int'
     #: Transport control (hop count).
     count: 'int'