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

Correct the HOPOPT and IPv6-Opts padding arithmetic: a well-formed options
area is 2 octets short of a multiple of 8, not 6, and the counterfactuals in
make and _make_pad_options now match the floor division make uses. Drop the
bug-report 'are affected' from the R1_COUNTER width comment.

Author: JarryShaw

pcapkit/protocols/internet/hopopt.py

@@ -376,7 +376,8 @@ def make(self,
         # NOTE: No options is not the same as no options area. The header is at
         # least 8 octets, 2 of them the fixed part, so the remaining 6 must be
         # padding options. Passing the empty list through the same path produces
-        # them; returning ``[], 0`` would declare an 8-octet header and emit 2.
+        # them; returning ``[], 0`` would emit the 2 fixed octets alone, under a
+        # ``Hdr Ext Len`` that ``(0 - 6) // 8`` makes ``-1``.
         options_value, total_length = self._make_hopopt_options(
             options if options is not None else [])
 
@@ -1349,8 +1350,8 @@ def _make_pad_options(self, offset: 'int') -> 'tuple[list[Schema_PadOption], int
             the alignment is computed from ``offset`` rather than from the
             length of the option just emitted. Aligning each option to 8 octets
             on its own leaves the options area a multiple of 8, whereas
-            :meth:`read` sizes it as ``hdr_ext_len * 8 + 6``, six short of a
-            multiple of 8; the header would declare 6 octets more than it
+            :meth:`read` sizes it as ``hdr_ext_len * 8 + 6``, two short of a
+            multiple of 8; the header would declare 2 octets fewer than it
             carried.
 
             A ``PadN`` option spends two octets on its own type and
@@ -1391,7 +1392,7 @@ def _make_hopopt_options(self, options: 'list[Schema_Option | tuple[Enum_Option,
             The returned length is that of the options area alone, the value
             :meth:`make` derives the ``Hdr Ext Len`` field from. Since the two
             octets of the fixed header precede it, an options area is well
-            formed only when it is 6 octets short of a multiple of 8 --
+            formed only when it is 2 octets short of a multiple of 8 --
             including when it holds no real options at all, in which case it is
             6 octets of pure padding rather than empty.
 

pcapkit/protocols/internet/ipv6_opts.py

@@ -368,7 +368,8 @@ def make(self,
         # NOTE: No options is not the same as no options area. The header is at
         # least 8 octets, 2 of them the fixed part, so the remaining 6 must be
         # padding options. Passing the empty list through the same path produces
-        # them; returning ``[], 0`` would declare an 8-octet header and emit 2.
+        # them; returning ``[], 0`` would emit the 2 fixed octets alone, under a
+        # ``Hdr Ext Len`` that ``(0 - 6) // 8`` makes ``-1``.
         options_value, total_length = self._make_ipv6_opts(
             options if options is not None else [])
 
@@ -1338,8 +1339,8 @@ def _make_pad_options(self, offset: 'int') -> 'tuple[list[Schema_PadOption], int
             length of the option that has just been emitted. Aligning each
             option to 8 octets on its own leaves the options area a multiple of
             8 octets long, whereas :meth:`read` sizes it as
-            ``hdr_ext_len * 8 + 6`` -- six short of a multiple of 8 -- so the
-            header would declare 6 octets more than it carried.
+            ``hdr_ext_len * 8 + 6`` -- two short of a multiple of 8 -- so the
+            header would declare 2 octets fewer than it carried.
 
             A ``PadN`` option spends two octets on its own type and
             ``Opt Data Len`` fields before any padding data, so occupying
@@ -1379,7 +1380,7 @@ def _make_ipv6_opts(self, options: 'list[Schema_Option | tuple[Enum_Option, dict
             The returned length is that of the options area alone, the value
             :meth:`make` derives the ``Hdr Ext Len`` field from. Since the two
             octets of the fixed header precede it, an options area is well
-            formed only when it is 6 octets short of a multiple of 8 --
+            formed only when it is 2 octets short of a multiple of 8 --
             including when it holds no real options at all, in which case it is
             6 octets of pure padding rather than empty.
 

pcapkit/protocols/schema/internet/hip.py

@@ -591,8 +591,8 @@ class R1CounterParameter(Parameter, code=[Enum_Parameter.R1_Counter,
     #: order", so the width is stated twice and inferred from neither.
     #: :rfc:`5201#section-5.2.3` gives the same 4 + 8 layout, so there is no
     #: version under which four octets is right, and both codes that reach this
-    #: class -- ``R1_Counter`` (128, HIPv1) and ``R1_COUNTER`` (129) -- are
-    #: affected. With the four ``reserved`` octets the contents are 12 octets,
+    #: class -- ``R1_Counter`` (128, HIPv1) and ``R1_COUNTER`` (129) -- take
+    #: the eight. With the four ``reserved`` octets the contents are 12 octets,
     #: which :rfc:`7401` Section 5.2.1's arithmetic pads to a 16-octet record.
     counter: 'int' = UInt64Field()
     #: Padding.