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

docs/source/pcapkit/protocols/application/ngap.rst

@@ -95,7 +95,7 @@ Known Limitations
 * **The specification version is that of the installed decoder, not this
   package's.** The IE and procedure enumerations were generated from
   ``NGAP_Constants`` of |pycrate|_ 0.8.1 (Release-18-era). A |pycrate|_ that
-  carries a newer NGAP will decode IEs that
+  carries a newer NGAP will decode values that
   :class:`~pcapkit.const.ngap.procedure_code.ProcedureCode` and
   :class:`~pcapkit.const.ngap.protocol_ie.ProtocolIE` do not name. Such a
   value resolves to a non-registering member called ``Unassigned`` rather than

docs/source/pcapkit/protocols/index.rst

@@ -202,6 +202,8 @@ Header Schema
    .. autoattribute:: __fields__
       :no-value:
 
+   .. automethod:: _cut_short_read
+
 .. autoclass:: pcapkit.protocols.schema.schema.EnumSchema
    :no-members:
    :show-inheritance:
@@ -219,6 +221,10 @@ Header Schema
 
 .. autodecorator:: pcapkit.protocols.schema.schema.schema_final
 
+.. autofunction:: pcapkit.protocols.schema.schema.keep_short_read
+
+.. autofunction:: pcapkit.protocols.schema.schema.replay_short_read
+
 Internal Definitions
 ~~~~~~~~~~~~~~~~~~~~
 

docs/source/pcapkit/protocols/misc/index.rst

@@ -6,7 +6,7 @@ Auxiliary Protocols
 .. module:: pcapkit.protocols.schema.misc
 
 :mod:`pcapkit.protocols.misc` contains the auxiliary protocol implementations.
-Such includes the PCAP header classes, the PCAP-NG
+These include the PCAP header classes, the PCAP-NG
 :class:`~pcapkit.protocols.misc.pcapng.PCAPNG` class, the
 :class:`~pcapkit.protocols.misc.raw.Raw` class for not-supported protocols, and
 the :class:`~pcapkit.protocols.misc.null.NoPayload` class for indication of

docs/source/pcapkit/protocols/misc/pcapng.rst

@@ -585,6 +585,8 @@ shared with the PCAP frame header and documented in
 .. autofunction:: pcapkit.protocols.schema.misc.pcapng.zigbee_key_trailing
 .. autofunction:: pcapkit.protocols.schema.misc.pcapng.zigbee_key_held
 .. autofunction:: pcapkit.protocols.schema.misc.pcapng._spb_data_length
+.. autofunction:: pcapkit.protocols.schema.misc.pcapng._cut_last_line
+.. autofunction:: pcapkit.protocols.schema.misc.pcapng._malformed_line_message
 
 Data Models
 -----------

pcapkit/protocols/application/httpv2.py

@@ -490,7 +490,9 @@ def register_frame(cls, code: 'Enum_Frame', meth: 'str | tuple[FrameParser, Fram
 
         Args:
             code: HTTP frame type code.
-            meth: Method name or callable to parse and/or construct the frame.
+            meth: Name of the ``_read_http_${name}`` and ``_make_http_${name}``
+                methods, or a ``(parser, constructor)`` pair of callables; see
+                :attr:`__frame__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -512,7 +514,7 @@ def register_frame(cls, code: 'Enum_Frame', meth: 'str | tuple[FrameParser, Fram
     ##########################################################################
 
     def __length_hint__(self) -> 'Literal[9]':
-        """Total length of corresponding protocol."""
+        """Return an estimated length for the object."""
         return 9
 
     ##########################################################################

pcapkit/protocols/misc/pcap/frame.py

@@ -473,7 +473,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Opt
         """
         #: int: frame index number
         self._fnum = num
-        #: pcapkit.protocols.misc.pcap.header.Header: Global header of the PCAP file.
+        #: pcapkit.protocols.data.misc.pcap.header.Header: Global header of the PCAP file.
         self._ghdr = header
 
         #: pcapkit.const.reg.linktype.LinkType: next layer protocol index

pcapkit/protocols/misc/pcapng.py

@@ -1073,7 +1073,9 @@ def register_block(cls, code: 'Enum_BlockType', meth: 'str | tuple[BlockParser,
 
         Args:
             code: PCAP-NG block type code.
-            meth: Method name or callable to parse and/or construct the block.
+            meth: Name of the ``_read_block_${name}`` and ``_make_block_${name}``
+                methods, or a ``(parser, constructor)`` pair of callables; see
+                :attr:`__block__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1096,7 +1098,9 @@ def register_option(cls, code: 'Enum_OptionType', meth: 'str | tuple[OptionParse
 
         Args:
             code: PCAP-NG option type code.
-            meth: Method name or callable to parse and/or construct the option.
+            meth: Name of the ``_read_option_${name}`` and
+                ``_make_option_${name}`` methods, or a ``(parser, constructor)``
+                pair of callables; see :attr:`__option__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1120,7 +1124,9 @@ def register_record(cls, code: 'Enum_RecordType', meth: 'str | tuple[RecordParse
 
         Args:
             code: PCAP-NG name resolution record type code.
-            meth: Method name or callable to parse and/or construct the name resolution record.
+            meth: Name of the ``_read_record_${name}`` and
+                ``_make_record_${name}`` methods, or a ``(parser, constructor)``
+                pair of callables; see :attr:`__record__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -1143,7 +1149,9 @@ def register_secrets(cls, code: 'Enum_SecretsType', meth: 'str | tuple[SecretsPa
 
         Args:
             code: PCAP-NG decryption secrets type code.
-            meth: Method name or callable to parse and/or construct the decryption secrets.
+            meth: Name of the ``_read_secrets_${name}`` and
+                ``_make_secrets_${name}`` methods, or a ``(parser, constructor)``
+                pair of callables; see :attr:`__secrets__`.
 
         Warns:
             RegistryWarning: If a different entry is already registered for
@@ -4851,7 +4859,7 @@ def _make_block_cb(self, block: 'Optional[Data_CustomBlock]' = None, *,
 
         # NOTE: ``-n % 4`` is the octet count needed to reach the next 32-bit
         # boundary, and zero when already there. Integer arithmetic throughout,
-        # unlike the ``math.ceil(n / 4) * 4 - n`` idiom used elsewhere in this
+        # unlike the ``math.ceil(n / 4) * 4`` idiom used elsewhere in this
         # file, which routes a length through a float.
         cb_data = data.pack() if isinstance(data, Schema) else data
         cb_data += bytes(-len(cb_data) % 4)

pcapkit/protocols/schema/misc/pcapng.py

@@ -1318,10 +1318,13 @@ def pre_pack(self, packet: 'dict[str, Any]') -> 'None':
             This method is expected to directly modify any data stored
             in the ``packet`` and thus no return is required.
 
-            The Byte-Order Magic is not carried by any field of the schema --
-            :attr:`magic` is the palindromic constant, identical in either byte
-            order -- so it is seeded here from the byte order the packet data
-            asks for, and from the host byte order when it asks for none.
+            :func:`shb_byteorder_callback` takes the byte order from the
+            Byte-Order Magic as :attr:`match` reads it, and a constructed block
+            has no :attr:`match` to read -- a forward match packs no octets --
+            nor can :attr:`magic` stand in, since it holds the same constant in
+            either byte order. So :attr:`match` is seeded here from the byte
+            order the packet data asks for, and from the host byte order when it
+            asks for none; a ``match`` already in ``packet`` is kept.
 
         """
         if 'match' in packet:
@@ -2050,7 +2053,7 @@ def __init__(self, type: 'Enum_OptionType', length: 'int', ip: 'IPv6Address | by
 class NameResolutionBlock(BlockType, code=Enum_BlockType.Name_Resolution_Block):
     """Header schema for PCAP-NG Name Resolution Block (NRB)."""
 
-    #: Record total length.
+    #: Block total length.
     length: 'int' = UInt32Field(callback=byteorder_callback)
     #: Name resolution records.
     records: 'list[NameResolutionRecord]' = OptionAreaField(

pcapkit/protocols/schema/schema.py

@@ -1486,10 +1486,11 @@ def keep_short_read(protocol: 'ProtocolBase') -> 'None':
     Called by the layer base classes once a parse is done. When the data ended
     inside one of the header's fields, ``info`` gains the ``__short_read__``
     record :meth:`Schema.unpack` made, so that :func:`replay_short_read` can
-    cut the rebuild back to what was captured (:issue:`1458`). The key is an
-    ordinary one, so :meth:`Info.to_dict <pcapkit.corekit.infoclass.Info.to_dict>`
-    carries it and ``from_data(info.to_dict())`` replays it too; it is absent
-    for a header that was captured whole.
+    cut the rebuild back to what was captured (:issue:`1458`). The key is listed
+    in :attr:`Data.__included__ <pcapkit.protocols.data.data.Data.__included__>`,
+    so :meth:`Info.to_dict <pcapkit.corekit.infoclass.Info.to_dict>` carries it
+    and ``from_data(info.to_dict())`` replays it too; it is absent for a header
+    that was captured whole.
 
     """
     header = cast('Optional[Schema]', getattr(protocol, '__header__', None))