docs(protocols): sixth whole-repo pass over application, misc and the protocol base (#1103)

pcapkit/protocols/application/http.py

@@ -511,12 +511,12 @@ def _guess_version(self, length: 'int', **kwargs: 'Any') -> 'HTTP':
               :exc:`~pcapkit.utilities.exceptions.ProtocolError` becomes under
               :func:`~pcapkit.corekit.decorators.beholder`. The nine-octet frame header is therefore
               never used to *identify* HTTP/2 ahead of HTTP/1: as identification it misfires on
-              binary HTTP/1 bodies, which is precisely how garbage text was classified HTTP/2 to
-              begin with. A bare frame is parsed as HTTP/2 only by the fall-through below, and only
-              if its header is one a conforming sender could write (see ``_test_http2_frame()``): a
-              frame type :rfc:`9113` defines, no undefined flag, and a stream that type may be sent
-              on. Nine zero octets -- a ``DATA`` frame on stream 0, a protocol error under
-              :rfc:`9113#section-6.1` -- are not guessed as HTTP/2.
+              binary HTTP/1 bodies, and classifies garbage text as HTTP/2. A bare frame is parsed
+              as HTTP/2 only by the fall-through below, and only if its header is one a conforming
+              sender could write (see ``_test_http2_frame()``): a frame type :rfc:`9113` defines,
+              no undefined flag, and a stream that type may be sent on. Nine zero octets -- a
+              ``DATA`` frame on stream 0, a protocol error under :rfc:`9113#section-6.1` -- are not
+              guessed as HTTP/2.
 
         """
         # NOTE: Positive identification, before any parse attempt. The preface is
@@ -605,7 +605,7 @@ def _guess_version(self, length: 'int', **kwargs: 'Any') -> 'HTTP':
         # <pcapkit.corekit.fields.field.FieldBase.length>` re-raises a
         # negative-length template as
         # :exc:`~pcapkit.utilities.exceptions.ProtocolError` -- so the
-        # suppression only guards whatever path is not yet known to do likewise.
+        # suppression only guards whatever path is not known to do likewise.
         #
         # Suppressing it on the *first* arm is wrong: nine byte patterns over
         # lengths 0-24 raised only ``ProtocolError`` through ``httpv1.HTTP``, so

pcapkit/protocols/data/application/httpv2.py

@@ -31,8 +31,8 @@
 class Flags(Data):
     """Data model for HTTP/2 flags."""
 
-    # NOTE: ``__value__`` is a dunder key, which ``to_dict`` carries only so
-    # named (#2003); the rebuild reads it, and the dumps write it, as before.
+    # NOTE: ``__value__`` is a dunder key, which ``to_dict`` carries only when
+    # it is named here (#2003); the rebuild reads it, and the dumps write it.
     __included__ = ['__value__']
 
     if TYPE_CHECKING:

pcapkit/protocols/data/misc/pcapng.py

@@ -66,8 +66,8 @@ class PCAPNG(Protocol):
     """Data model for PCAP-NG file blocks."""
 
     # NOTE: ``__truncated_raw__`` is a dunder key, which ``to_dict`` carries
-    # only so named (#2003); the rebuild reads it, and the dumps write it, as
-    # before.
+    # only when it is named here (#2003); the rebuild reads it, and the dumps
+    # write it.
     __included__ = ['__truncated_raw__']
 
     #: Block type.

pcapkit/protocols/data/misc/raw.py

@@ -27,7 +27,8 @@ class Raw(Protocol):
 
     #: Original enumeration of this protocol.
     protocol: 'Optional[int]'
-    #: error instance when parsing packet data
+    #: Message saying why the packet data is kept raw, if any: the error its
+    #: parse raised, or the dissection limit it is past.
     error: 'Optional[Exception]'
 
     if TYPE_CHECKING:

pcapkit/protocols/misc/pcap/frame.py

@@ -103,7 +103,7 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame],
     #: :meth:`self._decode_next_layer <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
     #: and :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`.
     #: Each value is a :class:`~pcapkit.corekit.module.ModuleDescriptor` naming the
-    #: module and class, or a :class:`~pcapkit.protocols.protocol.Protocol` subclass.
+    #: module and class, or a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass.
     __proto__ = collections.defaultdict(
         lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'),
         {
@@ -149,11 +149,11 @@ def register(cls, code: 'Enum_LinkType', protocol: 'ModuleDescriptor[ProtocolBas
         Arguments:
             code: protocol code as in :class:`~pcapkit.const.reg.linktype.LinkType`
             protocol: module descriptor or a
-                :class:`~pcapkit.protocols.protocol.Protocol` subclass
+                :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass
 
         Raises:
             pcapkit.utilities.exceptions.RegistryError: If ``protocol`` is not a
-                class, or not a :class:`~pcapkit.protocols.protocol.Protocol` subclass.
+                class, or not a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass.
 
         Warns:
             pcapkit.utilities.warnings.RegistryWarning: If this link type is

pcapkit/protocols/misc/pcapng.py

@@ -691,7 +691,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
     """
 
     if TYPE_CHECKING:
-        #: PCAP-NG context manager.
+        #: Section context of the block; see :attr:`section_context`.
         _ctx: 'Optional[Context]'
 
         #: PCAP-NG block type.
@@ -738,7 +738,7 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
     #: :meth:`self._decode_next_layer <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
     #: and :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`.
     #: Each value is a :class:`~pcapkit.corekit.module.ModuleDescriptor` naming the
-    #: module and class, or a :class:`~pcapkit.protocols.protocol.Protocol` subclass.
+    #: module and class, or a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass.
     __proto__ = collections.defaultdict(
         lambda: ModuleDescriptor('pcapkit.protocols.misc.raw', 'Raw'),
         {
@@ -957,8 +957,11 @@ def section_context(self) -> 'Context':
         """Section context of current PCAP-NG block.
 
         Raises:
-            UnsupportedCall: On a Section Header Block, which has no section
-                context of its own.
+            UnsupportedCall: If the block holds no section context: a block
+                given ``ctx=None``, or a Section Header Block, which starts a
+                section rather than reading one, unless the
+                :class:`~pcapkit.foundation.engines.pcapng.PCAPNG` engine read
+                it and assigned it the section it opens.
 
         .. versionadded:: 1.5.0
 
@@ -1058,11 +1061,11 @@ def register(cls, code: 'Enum_LinkType', protocol: 'ModuleDescriptor[ProtocolBas
         Arguments:
             code: protocol code as in :class:`~pcapkit.const.reg.linktype.LinkType`
             protocol: module descriptor or a
-                :class:`~pcapkit.protocols.protocol.Protocol` subclass
+                :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass
 
         Raises:
             pcapkit.utilities.exceptions.RegistryError: If ``protocol`` is not a
-                class, or not a :class:`~pcapkit.protocols.protocol.Protocol` subclass.
+                class, or not a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass.
 
         Warns:
             pcapkit.utilities.warnings.RegistryWarning: If this link type is
@@ -1516,7 +1519,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Opt
         self._sect = sct
         #: int: Block index number.
         self._fnum = num
-        #: pcapkit.foundation.engines.pcapng.Context: Context of the PCAP-NG file.
+        #: pcapkit.foundation.engines.pcapng.Context: Section context of the PCAP-NG file.
         self._ctx = ctx
         #: collections.Counter: Counter for option types.
         self._opt = collections.Counter()  # type: Counter[Enum_OptionType]

pcapkit/protocols/misc/raw.py

@@ -69,7 +69,7 @@ def read(self, length: 'Optional[int]' = None, *, error: 'Optional[Exception]' =
 
         Args:
             length: Length of packet data.
-            error: Parsing errors if any.
+            error: Message saying why the data is kept raw, if any.
             alias: Original enumeration of the unknown protocol.
             **kwargs: Arbitrary keyword arguments.
 
@@ -114,14 +114,14 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
                       length: 'Optional[int]' = None, **kwargs: 'Any') -> 'None':
         """Post initialisation hook.
 
-        When :mod:`pcapkit` meets a malformed packet, the original parsing
-        error instance is given as ``error``.
+        When :mod:`pcapkit` meets a malformed packet, or a layer past a
+        dissection limit, the message saying so is given as ``error``.
 
         Args:
             file: Source packet stream.
             length: Length of packet data.
-            error: Parsing error if any (for parsing), an :class:`Exception`
-                instance or :obj:`None`.
+            error: Message saying why the data is kept raw, if any (for
+                parsing), a :obj:`str` or :obj:`None`.
             alias: Original enumeration of the unknown protocol, an :obj:`int`
                 or :obj:`None`.
             **kwargs: Arbitrary keyword arguments.

pcapkit/protocols/protocol.py

@@ -1346,7 +1346,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional
 
         # NOTE: Construction only. A keyword that names no parameter of this
         # protocol is a mistake rather than a value. Every ``make`` in the tree
-        # ends its signature with ``**kwargs`` and never reads it, so an unknown
+        # ends its signature with ``**kwargs``, and none but the dispatching
+        # ``HTTP.make`` reads it, so an unknown
         # keyword would reach the schema as nothing at all and the field would
         # keep its default -- ``TCP_BASE`` asking for ``seq=1``, which
         # ``TCP.make`` spells ``seq_no``, would yield ``seq = 0`` with no warning

pcapkit/protocols/schema/misc/pcapng.py

@@ -579,10 +579,10 @@ def secrets_area(packet: 'dict[str, Any]') -> 'int':
         Length less its 20 framing octets, and never below zero.
 
     ``secrets_length`` is a 32-bit wire field. Read as declared, a length past
-    the block read the trailing Block Total Length and the blocks after it as
-    secrets, and past :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH` the
-    read raised :exc:`~pcapkit.utilities.exceptions.FieldValueError` from inside
-    the block's schema, which ended the whole extraction (:issue:`1980`). This
+    the block would read the trailing Block Total Length and the blocks after it
+    as secrets, and past :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH`
+    the read would raise :exc:`~pcapkit.utilities.exceptions.FieldValueError`
+    from inside the block's schema, ending the whole extraction (:issue:`1980`). This
     is the Secrets Data counterpart of :func:`captured_area`: the block keeps its
     declared ``secrets_length``, the secrets are the octets the block holds, and
     the padding and option area are sized from those octets.