docs(protocols): second pass over the IPv6 extension headers (#1103)

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

@@ -21,8 +21,7 @@ Octets      Bits        Name                    Description
   ?           ?   ``esp.icv``             Integrity Check Value (ICV, variable)
 ======= ========= ===================== ==============================================
 
-Unlike every other protocol in :mod:`pcapkit`, ESP is **not** self
-describing. :rfc:`4303` places the ``Pad Length`` and ``Next Header``
+ESP is **not** self describing. :rfc:`4303` places the ``Pad Length`` and ``Next Header``
 fields *inside* the ciphertext, and leaves the length of the ``Integrity
 Check Value`` to be determined by the Security Association (SA), which is
 negotiated out of band. Therefore:

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

@@ -4,7 +4,7 @@ MH - Mobility Header
 .. module:: pcapkit.protocols.internet.mh
 
 :mod:`pcapkit.protocols.internet.mh` contains
-:class:`~pcapkit.protocols.internet.mh.MH` only,
+:class:`~pcapkit.protocols.internet.mh.MH`,
 which implements extractor for Mobility Header
 (MH) [*]_, whose structure is described as below:
 
@@ -14,7 +14,7 @@ Octets      Bits        Name                    Description
   0           0   ``mh.next``                 Next Header
   1           8   ``mh.length``               Header Length
   2          16   ``mh.type``                 Mobility Header Type
-  3          24                               Reserved
+  3          24   ``mh.reserved``             Reserved
   4          32   ``mh.chksum``               Checksum
   6          48   ``mh.data``                 Message Data
 ======= ========= ================== ===============================

pcapkit/protocols/data/internet/ah.py

@@ -14,11 +14,17 @@
 
 @info_final
 class AH(Protocol):
-    """Data model for AH protocol."""
+    """Data model for AH protocol.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1327`).
+
+    """
 
     #: Next header.
     next: 'TransType'
-    #: Payload length.
+    #: Header length, in octets, decoded from the Payload Len field.
     length: 'int'
     #: Reserved.
     reserved: 'int'

pcapkit/protocols/data/internet/hopopt.py

@@ -43,11 +43,11 @@ class Option(Data):
 
     #: Option type.
     type: 'Enum_Option'
-    #: Unknown option cation.
+    #: Unknown option action.
     action: 'OptionAction'
     #: Change flag.
     change: 'bool'
-    #: Content length.
+    #: Option length (incl. type and length fields).
     length: 'int'
 
 
@@ -57,7 +57,7 @@ class HOPOPT(Protocol):
 
     #: Next header.
     next: 'TransType'
-    #: Header extension length.
+    #: Header length, in octets, decoded from ``Hdr Ext Len``.
     length: 'int'
     #: HOPOPT options.
     options: 'OrderedMultiInfo[Enum_Option, Option]'
@@ -79,7 +79,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class PadOption(Option):
-    """Data model for HOPOPT padding options."""
+    """Data model for HOPOPT padding options.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``pad`` (:issue:`1223`).
+
+    """
 
     #: Padding octets, i.e. the ``PadN`` option data as captured (empty for
     #: a ``Pad1``).
@@ -102,9 +108,9 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class RouterAlertOption(Option):
-    """Data model for HOPOPT router alter option."""
+    """Data model for HOPOPT router alert option."""
 
-    #: Router alter value.
+    #: Router alert value.
     value: 'RouterAlert'
 
     if TYPE_CHECKING:
@@ -113,7 +119,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class CALIPSOOption(Option):
-    """Data model for HOPOPT Common Architecture Label IPv6 Security Option (CALIPSO) option."""
+    """Data model for HOPOPT Common Architecture Label IPv6 Security Option (CALIPSO) option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``pad`` (:issue:`1403`).
+
+    """
 
     #: CALIPSO domain of interpretation.
     domain: 'int'
@@ -200,7 +212,13 @@ class QuickStartOption(Option):
 
 @info_final
 class QuickStartRequestOption(QuickStartOption):
-    """Data model for HOPOPT Quick Start request option."""
+    """Data model for HOPOPT Quick Start request option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: TTL.
     ttl: 'timedelta'
@@ -216,7 +234,14 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class QuickStartReportOption(QuickStartOption):
-    """Data model for HOPOPT Quick Start report of approved rate option."""
+    """Data model for HOPOPT Quick Start report of approved rate option.
+
+    .. versionchanged:: 1.5.0
+
+       New required fields ``reserved`` (:issue:`1235`) and ``unused``
+       (:issue:`1223`).
+
+    """
 
     #: Nonce.
     nonce: 'int'
@@ -231,7 +256,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class RPLFlags(Data):
-    """Data model for HOPOPT RPL option flags fields."""
+    """Data model for HOPOPT RPL option flags fields.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1199`).
+
+    """
 
     #: Down flag.
     down: 'bool'
@@ -248,7 +279,13 @@ def __init__(self, down: 'bool', rank_err: 'bool', fwd_err: 'bool', reserved: 'i
 
 @info_final
 class RPLOption(Option):
-    """Data model for HOPOPT Routing Protocol for Low-Power and Lossy Networks (RPL) option."""
+    """Data model for HOPOPT Routing Protocol for Low-Power and Lossy Networks (RPL) option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``sub_tlvs`` (:issue:`1199`).
+
+    """
 
     #: Flags.
     flags: 'RPLFlags'
@@ -265,11 +302,17 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class MPLFlags(Data):
-    """Data model for HOPOPT MPL option flags fields."""
+    """Data model for HOPOPT MPL option flags fields.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: Max flag.
     max: 'bool'
-    #: Non-conformation flag.
+    #: Non-conformance flag.
     drop: 'bool'
     #: Reserved bits (``rsv``).
     reserved: 'int'
@@ -344,7 +387,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class DFFFlags(Data):
-    """Data model for HOPOPT ``IP_DFF`` option flags."""
+    """Data model for HOPOPT ``IP_DFF`` option flags.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: Duplicate flag.
     dup: 'bool'

pcapkit/protocols/data/internet/ipv6.py

@@ -27,7 +27,8 @@ class IPv6(Protocol):
     """Data model for Internet Protocol version 6.
 
     Important:
-        Due to the reserved keyword conflict, please use :meth:`from_dict`
+        Due to the reserved keyword conflict, please use
+        :meth:`~pcapkit.corekit.infoclass.Info.from_dict`
         to create an instance of this data model.
 
     """

pcapkit/protocols/data/internet/ipv6_frag.py

@@ -14,7 +14,14 @@
 
 @info_final
 class IPv6_Frag(Protocol):
-    """Data model for IPv6 fragment header."""
+    """Data model for IPv6 fragment header.
+
+    .. versionchanged:: 1.5.0
+
+       New required fields ``reserved_octet`` (:issue:`1223`) and ``reserved``
+       (:issue:`1235`).
+
+    """
 
     #: Next header.
     next: 'TransType'

pcapkit/protocols/data/internet/ipv6_opts.py

@@ -43,11 +43,11 @@ class Option(Data):
 
     #: Option type.
     type: 'Enum_Option'
-    #: Unknown option cation.
+    #: Unknown option action.
     action: 'OptionAction'
     #: Change flag.
     change: 'bool'
-    #: Content length.
+    #: Option length (incl. type and length fields).
     length: 'int'
 
 
@@ -57,7 +57,7 @@ class IPv6_Opts(Protocol):
 
     #: Next header.
     next: 'TransType'
-    #: Header extension length.
+    #: Header length, in octets, decoded from ``Hdr Ext Len``.
     length: 'int'
     #: IPv6-Opts options.
     options: 'OrderedMultiInfo[Enum_Option, Option]'
@@ -81,7 +81,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class PadOption(Option):
-    """Data model for IPv6-Opts padding options."""
+    """Data model for IPv6-Opts padding options.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``pad`` (:issue:`1223`).
+
+    """
 
     #: Padding octets, i.e. the ``PadN`` option data as captured (empty for
     #: a ``Pad1``).
@@ -106,9 +112,9 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class RouterAlertOption(Option):
-    """Data model for IPv6-Opts router alter option."""
+    """Data model for IPv6-Opts router alert option."""
 
-    #: Router alter value.
+    #: Router alert value.
     value: 'RouterAlert'
 
     if TYPE_CHECKING:
@@ -118,7 +124,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class CALIPSOOption(Option):
-    """Data model for IPv6-Opts Common Architecture Label IPv6 Security Option (CALIPSO) option."""
+    """Data model for IPv6-Opts Common Architecture Label IPv6 Security Option (CALIPSO) option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``pad`` (:issue:`1403`).
+
+    """
 
     #: CALIPSO domain of interpretation.
     domain: 'int'
@@ -209,7 +221,13 @@ class QuickStartOption(Option):
 
 @info_final
 class QuickStartRequestOption(QuickStartOption):
-    """Data model for IPv6-Opts Quick Start request option."""
+    """Data model for IPv6-Opts Quick Start request option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: TTL.
     ttl: 'timedelta'
@@ -225,7 +243,14 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class QuickStartReportOption(QuickStartOption):
-    """Data model for IPv6-Opts Quick Start report of approved rate option."""
+    """Data model for IPv6-Opts Quick Start report of approved rate option.
+
+    .. versionchanged:: 1.5.0
+
+       New required fields ``reserved`` (:issue:`1235`) and ``unused``
+       (:issue:`1223`).
+
+    """
 
     #: Nonce.
     nonce: 'int'
@@ -241,7 +266,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class RPLFlags(Data):
-    """Data model for IPv6-Opts RPL option flags fields."""
+    """Data model for IPv6-Opts RPL option flags fields.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1199`).
+
+    """
 
     #: Down flag.
     down: 'bool'
@@ -259,7 +290,13 @@ def __init__(self, down: 'bool', rank_err: 'bool',
 
 @info_final
 class RPLOption(Option):
-    """Data model for IPv6-Opts Routing Protocol for Low-Power and Lossy Networks (RPL) option."""
+    """Data model for IPv6-Opts Routing Protocol for Low-Power and Lossy Networks (RPL) option.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``sub_tlvs`` (:issue:`1199`).
+
+    """
 
     #: Flags.
     flags: 'RPLFlags'
@@ -277,11 +314,17 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class MPLFlags(Data):
-    """Data model for IPv6-Opts MPL option flags fields."""
+    """Data model for IPv6-Opts MPL option flags fields.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: Max flag.
     max: 'bool'
-    #: Non-conformation flag.
+    #: Non-conformance flag.
     drop: 'bool'
     #: Reserved bits (``rsv``).
     reserved: 'int'
@@ -360,7 +403,13 @@ def __init__(self, type: 'Enum_Option', action: 'int', change: 'bool', length: '
 
 @info_final
 class DFFFlags(Data):
-    """Data model for IPv6-Opts ``IP_DFF`` option flags."""
+    """Data model for IPv6-Opts ``IP_DFF`` option flags.
+
+    .. versionchanged:: 1.5.0
+
+       New required field ``reserved`` (:issue:`1235`).
+
+    """
 
     #: Duplicate flag.
     dup: 'bool'