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

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

@@ -5,7 +5,7 @@ FTP - File Transfer Protocol
 
 :mod:`pcapkit.protocols.application.ftp` contains
 :class:`~pcapkit.protocols.application.ftp.FTP`,
-which implements extractor for File Transfer Protocol
+which implements an extractor for File Transfer Protocol
 (FTP) [*]_, and :class:`~pcapkit.protocols.application.ftp.FTP_DATA`
 for its data channel.
 

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

@@ -5,7 +5,7 @@ HTTP/1.* - Hypertext Transfer Protocol
 
 :mod:`pcapkit.protocols.application.httpv1` contains
 :class:`~pcapkit.protocols.application.httpv1.HTTP`,
-which implements extractor for Hypertext Transfer
+which implements an extractor for Hypertext Transfer
 Protocol (HTTP/1.*) [*]_, and its
 :class:`~pcapkit.protocols.application.httpv1.Type` enumeration. The
 structure of an HTTP/1.* message is described as below:

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

@@ -5,7 +5,7 @@ HTTP/2 - Hypertext Transfer Protocol
 
 :mod:`pcapkit.protocols.application.httpv2` contains
 :class:`~pcapkit.protocols.application.httpv2.HTTP`
-only, which implements extractor for Hypertext Transfer
+only, which implements an extractor for Hypertext Transfer
 Protocol (HTTP/2) [*]_, whose structure is described as
 below:
 

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

@@ -5,7 +5,7 @@ NGAP - NG Application Protocol
 
 :mod:`pcapkit.protocols.application.ngap` contains
 :class:`~pcapkit.protocols.application.ngap.NGAP`,
-which implements extractor for the NG Application Protocol
+which implements an extractor for the NG Application Protocol
 (NGAP) [*]_, as specified in 3GPP TS 38.413, and the enumerations its
 data models report with:
 :class:`~pcapkit.protocols.application.ngap.PDUKind`,
@@ -18,7 +18,7 @@ It runs over SCTP and is named by the DATA chunk's *payload protocol
 identifier* rather than by a port, so :class:`NGAP` is registered on
 :attr:`SCTP.__proto__ <pcapkit.protocols.transport.sctp.SCTP.__proto__>` under
 PPID 60 (``NG_Application_Protocol``) and PPID 66
-(``NGAP_over_DTLS_over_SCTP``), c.f.
+(``NGAP_over_DTLS_over_SCTP``); see
 :func:`pcapkit.foundation.registry.protocols.register_sctp`.
 
 An SCTP DATA chunk that names NGAP carries exactly one ``NGAP-PDU``, encoded

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

@@ -5,7 +5,7 @@ OSPF - Open Shortest Path First
 
 :mod:`pcapkit.protocols.application.ospf` contains
 :class:`~pcapkit.protocols.application.ospf.OSPF` only,
-which implements extractor for Open Shortest Path
+which implements an extractor for Open Shortest Path
 First (OSPF) [*]_, whose structure is described
 as below:
 

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

@@ -18,7 +18,7 @@ Global Header
 
 :mod:`pcapkit.protocols.misc.pcap.header` contains
 :class:`~pcapkit.protocols.misc.pcap.header.Header` only,
-which implements extractor for global headers [*]_
+which implements an extractor for global headers [*]_
 of PCAP, whose structure is described as below:
 
 .. code-block:: c
@@ -99,7 +99,7 @@ Frame Header
 
 :mod:`pcapkit.protocols.misc.pcap.frame` contains
 :class:`~pcapkit.protocols.misc.pcap.frame.Frame` only,
-which implements extractor for frame headers [*]_ of PCAP,
+which implements an extractor for frame headers [*]_ of PCAP,
 whose structure is described as below:
 
 .. code-block:: c

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

@@ -6,7 +6,7 @@ PCAP-NG File Format
 
 :mod:`pcapkit.protocols.misc.pcapng` contains
 :class:`~pcapkit.protocols.misc.pcapng.PCAPNG`,
-which implements extractor for PCAP-NG file format [*]_, and the
+which implements an extractor for PCAP-NG file format [*]_, and the
 :class:`~pcapkit.protocols.misc.pcapng.PacketDirection`,
 :class:`~pcapkit.protocols.misc.pcapng.PacketReception` and
 :class:`~pcapkit.protocols.misc.pcapng.WireGuardKeyLabel` enumerations.

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

@@ -5,7 +5,7 @@ Raw Packet Data
 
 :mod:`pcapkit.protocols.misc.raw` contains
 :class:`~pcapkit.protocols.misc.raw.Raw` only, which implements
-extractor for unknown protocol, and constructs a
+an extractor for unknown protocols, and constructs a
 :class:`~pcapkit.protocols.protocol.Protocol` like object.
 
 .. autoclass:: pcapkit.protocols.misc.raw.Raw

docs/source/pcapkit/protocols/protocol.rst

@@ -12,7 +12,7 @@ new protocol stack; a new protocol in an existing layer subclasses that layer's
 base class -- :class:`~pcapkit.protocols.link.link.Link`,
 :class:`~pcapkit.protocols.internet.internet.Internet`,
 :class:`~pcapkit.protocols.transport.transport.Transport` or
-:class:`~pcapkit.protocols.application.application.Application` -- instead, c.f.
+:class:`~pcapkit.protocols.application.application.Application` -- instead; see
 :doc:`/ext`. The built-in protocol families, those layer classes included,
 derive from :class:`~pcapkit.protocols.protocol.ProtocolBase`, whose metaclass
 is :class:`~pcapkit.protocols.protocol.ProtocolMeta`; both are listed under

pcapkit/protocols/application/__init__.py

@@ -14,7 +14,7 @@
 #       SSH, TELNET, TLS/SSL, XMPP.
 #
 # NB: NGAP's decoder below is an optional
-#     dependency, c.f. pcapkit.protocols.application.ngap. Importing the module
+#     dependency; see pcapkit.protocols.application.ngap. Importing the module
 #     is free -- ``pycrate`` is imported inside the parse path, not here.
 
 # Base Class for Application Layer

pcapkit/protocols/application/ftp.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.application.ftp` contains
 :class:`~pcapkit.protocols.application.ftp.FTP`,
-which implements extractor for File Transfer Protocol
+which implements an extractor for File Transfer Protocol
 (FTP) [*]_, and
 :class:`~pcapkit.protocols.application.ftp.FTP_DATA`
 for its data channel.

pcapkit/protocols/application/httpv1.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.application.httpv1` contains
 :class:`~pcapkit.protocols.application.httpv1.HTTP`,
-which implements extractor for Hypertext Transfer
+which implements an extractor for Hypertext Transfer
 Protocol (HTTP/1.*) [*]_, and its
 :class:`~pcapkit.protocols.application.httpv1.Type` enumeration. The
 structure of an HTTP/1.* message is described as below:

pcapkit/protocols/application/httpv2.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.application.httpv2` contains
 :class:`~pcapkit.protocols.application.httpv2.HTTP`
-only, which implements extractor for Hypertext Transfer
+only, which implements an extractor for Hypertext Transfer
 Protocol (HTTP/2) [*]_, whose structure is described as
 below:
 

pcapkit/protocols/application/ngap.py

@@ -7,7 +7,7 @@
 
 :mod:`pcapkit.protocols.application.ngap` contains
 :class:`~pcapkit.protocols.application.ngap.NGAP`,
-which implements extractor for the NG Application Protocol
+which implements an extractor for the NG Application Protocol
 (NGAP) [*]_, as specified in 3GPP TS 38.413, and the enumerations its
 decoded fields resolve to.
 
@@ -16,7 +16,7 @@
 identifier* rather than by a port, so :class:`NGAP` is registered on
 :attr:`SCTP.__proto__ <pcapkit.protocols.transport.sctp.SCTP.__proto__>` under
 PPID 60 (``NG_Application_Protocol``) and PPID 66
-(``NGAP_over_DTLS_over_SCTP``), c.f.
+(``NGAP_over_DTLS_over_SCTP``); see
 :func:`pcapkit.foundation.registry.protocols.register_sctp`.
 
 An SCTP DATA chunk that names NGAP carries exactly one ``NGAP-PDU``, encoded
@@ -125,7 +125,7 @@
 
 __all__ = ['NGAP', 'PDUKind', 'Criticality']
 
-#: Cached ``NGAP-PDU`` object, c.f. :func:`load_pycrate`. :data:`NotImplemented`
+#: Cached ``NGAP-PDU`` object; see :func:`load_pycrate`. :data:`NotImplemented`
 #: means the import has not been attempted yet, :data:`None` that it was
 #: attempted and |pycrate|_ is not installed, and anything else is the loaded
 #: object. "Not installed" is kept apart from "not attempted" so that a capture

pcapkit/protocols/application/ospf.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.application.ospf` contains
 :class:`~pcapkit.protocols.application.ospf.OSPF` only,
-which implements extractor for Open Shortest Path
+which implements an extractor for Open Shortest Path
 First (OSPF) [*]_, whose structure is described
 as below:
 
@@ -116,7 +116,7 @@ class OSPF(Application[Data_OSPF, Schema_OSPF],
     #: :attr:`alias` are needed *during* :meth:`read` -- :meth:`self._decode_next_layer
     #: <pcapkit.protocols.protocol.Protocol._decode_next_layer>` builds the
     #: protocol chain out of :attr:`alias` -- and ``_info`` is not assigned until
-    #: :meth:`read` has returned. c.f. ``ARP._acnm`` on
+    #: :meth:`read` has returned. See ``ARP._acnm`` on
     #: :class:`~pcapkit.protocols.link.arp.ARP`, which has the same constraint.
     _version: 'int'
 
@@ -388,7 +388,7 @@ def _make_id_numbers(self, id: 'IPv4Address | str | bytes | bytearray') -> 'byte
             ID bytes.
 
         Raises:
-            FieldValueError: If ``id`` is a :obj:`bool` (c.f.
+            FieldValueError: If ``id`` is a :obj:`bool` (see
                 :func:`~pcapkit.corekit.fields.ipaddress.parse_ip_address`).
 
         Notes:

pcapkit/protocols/misc/pcap/frame.py

@@ -7,7 +7,7 @@
 
 :mod:`pcapkit.protocols.misc.pcap.frame` contains
 :class:`~pcapkit.protocols.misc.pcap.frame.Frame` only,
-which implements extractor for frame headers [*]_ of PCAP,
+which implements an extractor for frame headers [*]_ of PCAP,
 whose structure is described as below:
 
 .. code-block:: c
@@ -100,9 +100,9 @@ class Frame(ProtocolBase[Data_Frame, Schema_Frame],
     # Defaults.
     ##########################################################################
 
-    #: Protocol index mapping for
-    #: decoding next layer, c.f. :meth:`self._decode_next_layer <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
-    #: & :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`.
+    #: Protocol index mapping for decoding the next layer; see
+    #: :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.
     __proto__ = collections.defaultdict(
@@ -334,7 +334,7 @@ def read(self, length: 'Optional[int]' = None, *, _read: 'bool' = True,
             # on the tail of this record followed by the head of the next one.
             # So the start is recorded before the unpack, in
             # :meth:`self.__post_init__ <__post_init__>`, and seeked to
-            # absolutely, as the PCAP-NG reader does, c.f.
+            # absolutely, as the PCAP-NG reader does; see
             # :meth:`pcapkit.protocols.misc.pcapng.PCAPNG.read`.
             seek_cur = _seek_set + self.length + _ilen
 
@@ -349,7 +349,7 @@ def read(self, length: 'Optional[int]' = None, *, _read: 'bool' = True,
             # running past its block (:issue:`1405`): ``incl_len`` and ``cap_len``
             # stay as declared, so the record rebuilds byte-exactly, and the
             # packet is the octets present. A writer must not copy the declared
-            # length, c.f. :meth:`PCAPIO._append_value
+            # length; see :meth:`PCAPIO._append_value
             # <pcapkit.dumpkit.pcap.PCAPIO._append_value>` (:issue:`1541`).
             held = len(self._data) - self.length
             if held < _ilen:

pcapkit/protocols/misc/pcap/header.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.misc.pcap.header` contains
 :class:`~pcapkit.protocols.misc.pcap.header.Header` only,
-which implements extractor for global headers [*]_
+which implements an extractor for global headers [*]_
 of PCAP, whose structure is described as below:
 
 .. code-block:: c

pcapkit/protocols/misc/pcapng.py

@@ -7,7 +7,7 @@
 
 :mod:`pcapkit.protocols.misc.pcapng` contains
 :class:`~pcapkit.protocols.misc.pcapng.PCAPNG`,
-which implements extractor for PCAP-NG file format [*]_, and the
+which implements an extractor for PCAP-NG file format [*]_, and the
 :class:`~pcapkit.protocols.misc.pcapng.PacketDirection`,
 :class:`~pcapkit.protocols.misc.pcapng.PacketReception` and
 :class:`~pcapkit.protocols.misc.pcapng.WireGuardKeyLabel` enumerations.
@@ -727,9 +727,9 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
     # Defaults.
     ##########################################################################
 
-    #: Protocol index mapping for
-    #: decoding next layer, c.f. :meth:`self._decode_next_layer <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
-    #: & :meth:`self._import_next_layer <pcapkit.protocols.protocol.Protocol._import_next_layer>`.
+    #: Protocol index mapping for decoding the next layer; see
+    #: :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.
     __proto__ = collections.defaultdict(
@@ -743,10 +743,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
         },
     )  # type: DefaultDict[Enum_LinkType | int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]
 
-    #: Block type to method mapping. Method names are expected to be referred
-    #: to the class by ``_read_block_${name}`` and/or ``_make_block_${name}``,
-    #: and if such name not found, the value should then be a method that can
-    #: parse the block by itself.
+    #: Block type to method mapping. A :obj:`str` value names the
+    #: ``_read_block_${name}`` and ``_make_block_${name}`` methods, which fall
+    #: back to ``_read_block_unknown`` and ``_make_block_unknown`` when not
+    #: defined, as an unregistered code does; any other value is a
+    #: ``(parser, constructor)`` pair of callables.
     __block__ = collections.defaultdict(
         lambda: 'unknown',
         {
@@ -764,10 +765,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
         },
     )  # type: DefaultDict[Enum_BlockType | int, str | tuple[BlockParser, BlockConstructor]]
 
-    #: Block option type to method mapping. Method names are expected to be
-    #: referred to the class by ``_read_option_${name}`` and/or ``_make_option_${name}``,
-    #: and if such name not found, the value should then be a method that can
-    #: parse the option by itself.
+    #: Block option type to method mapping. A :obj:`str` value names the
+    #: ``_read_option_${name}`` and ``_make_option_${name}`` methods, which fall
+    #: back to ``_read_option_unknown`` and ``_make_option_unknown`` when not
+    #: defined, as an unregistered code does; any other value is a
+    #: ``(parser, constructor)`` pair of callables.
     __option__ = collections.defaultdict(
         lambda: 'unknown',
         {
@@ -814,10 +816,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
         },
     )  # type: DefaultDict[Union[Enum_OptionType, Tuple[str, int]], str | tuple[OptionParser, OptionConstructor]]
 
-    #: Name Resolution Block record type to method mapping. Method names are expected
-    #: to be referred to the class by ``_read_record_${name}`` and/or ``_make_record_${name}``,
-    #: and if such name not found, the value should then be a method that can
-    #: parse the record by itself.
+    #: Name Resolution Block record type to method mapping. A :obj:`str` value
+    #: names the ``_read_record_${name}`` and ``_make_record_${name}`` methods,
+    #: which fall back to ``_read_record_unknown`` and ``_make_record_unknown``
+    #: when not defined, as an unregistered code does; any other value is a
+    #: ``(parser, constructor)`` pair of callables.
     __record__ = collections.defaultdict(
         lambda: 'unknown',
         {
@@ -827,10 +830,11 @@ class PCAPNG(ProtocolBase[Data_PCAPNG, Schema_PCAPNG],
         },
     )  # type: DefaultDict[Enum_RecordType | int, str | tuple[RecordParser, RecordConstructor]]
 
-    #: Decryption secrets type to method mapping. Method names are expected to
-    #: be referred to the class by ``_read_secrets_${name}`` and/or ``_make_secrets_${name}``,
-    #: and if such name not found, the value should then be a method that can
-    #: parse the decryption secrets by itself.
+    #: Decryption secrets type to method mapping. A :obj:`str` value names the
+    #: ``_read_secrets_${name}`` and ``_make_secrets_${name}`` methods, which
+    #: fall back to ``_read_secrets_unknown`` and ``_make_secrets_unknown`` when
+    #: not defined, as an unregistered code does; any other value is a
+    #: ``(parser, constructor)`` pair of callables.
     __secrets__ = collections.defaultdict(
         lambda: 'unknown',
         {

pcapkit/protocols/misc/raw.py

@@ -6,7 +6,7 @@
 
 :mod:`pcapkit.protocols.misc.raw` contains
 :class:`~pcapkit.protocols.misc.raw.Raw` only, which implements
-extractor for unknown protocol, and constructs a
+an extractor for unknown protocols, and constructs a
 :class:`~pcapkit.protocols.protocol.Protocol` like object.
 
 """
@@ -114,8 +114,8 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
                       length: 'Optional[int]' = None, **kwargs: 'Any') -> 'None':
         """Post initialisation hook.
 
-        Would :mod:`pcapkit` encounter malformed packets, the original parsing
-        error instance will be provided as in ``error``.
+        When :mod:`pcapkit` meets a malformed packet, the original parsing
+        error instance is given as ``error``.
 
         Args:
             file: Source packet stream.