docs(protocols): second-round pass over the schema prose (#719)

pcapkit/protocols/schema/__init__.py

@@ -28,7 +28,7 @@
     'ARP',
     'Ethernet',
     'L2TP',
-    'OSPF', 'OSPF_CrytographicAuthentication',
+    'OSPF', 'OSPF_CrytographicAuthentication',  # application layer
     'VLAN', 'VLAN_TCI',
 
     # Internet Layer Protocols

pcapkit/protocols/schema/application/httpv2.py

@@ -49,7 +49,7 @@ class FrameFlags(TypedDict):
     class StreamID(TypedDict):
         """Stream identifier."""
 
-        #: Steam identifier.
+        #: Stream identifier.
         sid: int
 
     class StreamDependency(TypedDict):
@@ -130,7 +130,7 @@ class Flags(EnumLookup, enum.IntFlag):
         Built on :class:`~pcapkit.corekit.enum.EnumLookup`, the lookup contract
         shared by every non-registry enumeration. The six concrete per-frame
         subclasses below each declare ``class Flags(FrameType.Flags):`` with no
-        base list of their own, so they inherit :class:`EnumLookup`
+        base list of their own, so they inherit :class:`~pcapkit.corekit.enum.EnumLookup`
         transitively rather than needing it repeated.
 
         """

pcapkit/protocols/schema/internet/hip.py

@@ -225,7 +225,7 @@ def two_octet_prefix_list_len(pkt: 'dict[str, Any]') -> 'int':
     two-octet ``reserved`` or ``port`` field with a list of items sized by
     the remainder of the parameter.
 
-    :class:`TransportFormatListParameter` looked like a fourth call site --
+    :class:`TransportFormatListParameter` looks like a fourth call site --
     same ``pkt['len'] - 2`` expression -- but is not: see
     :func:`transport_format_list_len` for why it has no such prefix to
     subtract.
@@ -264,10 +264,9 @@ def transport_format_list_len(pkt: 'dict[str, Any]') -> 'int':
         |          TF type #1           |           TF type #2          /
 
     -- so the list's byte length *is* ``Length``, with nothing to subtract.
-    Subtracting 2 anyway (as a since-corrected revision of this module once
-    did, mirroring the three genuine two-octet-prefix sites) silently
-    dropped the trailing two octets of *every* non-empty list on parse, and
-    rejected the parameter's own legitimate empty-list encoding
+    Subtracting 2 anyway, as the three genuine two-octet-prefix sites do,
+    would drop the trailing two octets of *every* non-empty list on parse,
+    and reject the parameter's own legitimate empty-list encoding
     (``Length = 0``, ``formats = []``) as malformed.
 
     "2x number of TF types" also fixes each ``TF type`` entry's own width at
@@ -277,10 +276,9 @@ def transport_format_list_len(pkt: 'dict[str, Any]') -> 'int':
     ``EnumField(length=2, ...)``, matching :class:`HIPTransportModeParameter`'s
     ``mode`` rather than the one-octet items of :func:`two_octet_prefix_list_len`'s
     other two call sites. This function only answers how many *bytes* the
-    list occupies; getting that number right and the item width wrong (as a
-    still-earlier revision did, at one octet) still corrupts every non-empty
-    list, just by reading twice as many entries as the wire holds instead of
-    dropping octets.
+    list occupies; getting that number right and the item width wrong (one
+    octet) would still corrupt every non-empty list, just by reading twice as
+    many entries as the wire holds instead of dropping octets.
 
     Args:
         pkt: Parameter unpacked schema.

pcapkit/protocols/schema/internet/ipv4.py

@@ -106,7 +106,7 @@ class QSNonce(TypedDict):
 def quick_start_option_length(schema: 'Type[QSOption]') -> 'int':
     """On-the-wire length, in octets, of a resolved Quick-Start (``QS``) suboption.
 
-    The Quick-Start suboption schemas re-declare the option's own ``type`` and
+    The Quick-Start suboption schemas carry the option's own ``type`` and
     ``length`` octets -- they inherit them from :class:`Option` -- so what
     :func:`quick_start_data_selector` has to hand the nested
     :class:`~pcapkit.corekit.fields.misc.SchemaField` is the length of the
@@ -295,7 +295,7 @@ class LSROption(Option, code=Enum_OptionNumber.LSR):
         length=lambda pkt: pkt['pointer'] - 4,
         item_type=IPv4AddressField(),
     )
-    #: Remaining data buffer0.
+    #: Remaining data buffer.
     remainder: 'bytes' = PaddingField(
         length=lambda pkt: pkt['length'] - pkt['pointer'] + 1,
         default=bytes(36),  # a reasonable default
@@ -481,7 +481,7 @@ class RROption(Option, code=Enum_OptionNumber.RR):
         length=lambda pkt: pkt['pointer'] - 4,
         item_type=IPv4AddressField(),
     )
-    #: Remaining data buffer0.
+    #: Remaining data buffer.
     remainder: 'bytes' = PaddingField(
         length=lambda pkt: pkt['length'] - pkt['pointer'] + 1,
         default=bytes(36),  # a reasonable default
@@ -515,7 +515,7 @@ class SSROption(Option, code=Enum_OptionNumber.SSR):
         length=lambda pkt: pkt['pointer'] - 4,
         item_type=IPv4AddressField(),
     )
-    #: Remaining data buffer0.
+    #: Remaining data buffer.
     remainder: 'bytes' = PaddingField(
         length=lambda pkt: pkt['length'] - pkt['pointer'] + 1,
         default=bytes(36),  # a reasonable default
@@ -608,7 +608,7 @@ def post_process(self, packet: 'dict[str, Any]') -> 'QSOption':
 
 
 class QSOption(Option, EnumSchema[Enum_QSFunction]):
-    """Header schema for IPV4 quick start (``QS``) options."""
+    """Header schema for IPv4 quick start (``QS``) options."""
 
     __enum__: 'DefaultDict[Enum_QSFunction, Type[QSOption]]' = collections.defaultdict(lambda: None)  # type: ignore[return-value,arg-type]
 
@@ -624,7 +624,7 @@ class QSOption(Option, EnumSchema[Enum_QSFunction]):
 
 @schema_final
 class QuickStartRequestOption(QSOption, code=Enum_QSFunction.Quick_Start_Request):
-    """Header schema for IPV4 quick start request options."""
+    """Header schema for IPv4 quick start request options."""
 
     #: QS time-to-live (TTL).
     ttl: 'int' = UInt8Field()
@@ -640,7 +640,7 @@ def __init__(self, type: 'Enum_OptionNumber', length: 'int', flags: 'QuickStartF
 
 @schema_final
 class QuickStartReportOption(QSOption, code=Enum_QSFunction.Report_of_Approved_Rate):
-    """Header schema for IPV4 quick start report of approved rate options."""
+    """Header schema for IPv4 quick start report of approved rate options."""
 
     #: Not used. One octet, holding the place a Quick-Start Request fills with
     #: ``QS TTL``: :rfc:`4782#section-3.1` says in as many words that *"for a

pcapkit/protocols/schema/internet/mh.py

@@ -600,7 +600,7 @@ def post_process(self, packet: 'dict[str, Any]') -> 'Option':
             Revised schema.
 
         """
-        # for Pad1 option, length is always 1
+        # for Pad1 option, length is always 0
         if self.type == Enum_Option.Pad1:
             self.length = 0
         return self
@@ -1939,7 +1939,8 @@ class DynamicIPMulticastSelectorOption(Option, code=Enum_Option.Dynamic_IP_Multi
         :rfc:`3376#section-4.2` IGMP structures, which belong to those protocols
         rather than to the Mobility Header, so they are carried opaquely here.
         :attr:`protocol` says which of the two they are in -- ``143`` for MLDv2
-        and ``131`` for MLDv1.
+        and ``131`` for MLDv1 [:rfc:`7028#section-5.1.2`], or ``0x12``, ``0x16``
+        and ``0x22`` for IGMPv1 to IGMPv3 [:rfc:`7028#section-8`].
 
     """
 
@@ -1990,7 +1991,7 @@ class ActiveMulticastSubscriptionIPv4Option(
 
     """
 
-    #: IGMP message type identifying the context format: ``0x12`` for IGMPv1,
+    #: IGMP message type identifying the context format -- ``0x12`` for IGMPv1,
     #: ``0x16`` for IGMPv2 and ``0x22`` for IGMPv3.
     igmp_type: 'int' = UInt8Field()
     #: Multicast membership context.
@@ -2014,7 +2015,7 @@ class ActiveMulticastSubscriptionIPv6Option(
 
     """
 
-    #: MLD message type identifying the context format: ``143`` for MLDv2 and
+    #: MLD message type identifying the context format -- ``143`` for MLDv2 and
     #: ``131`` for MLDv1.
     mld_type: 'int' = UInt8Field()
     #: Multicast membership context.
@@ -2216,7 +2217,7 @@ class MulticastMobilityOption(Option, code=Enum_Option.Multicast_Mobility_Option
 
     """
 
-    #: Option code: ``1`` for IGMPv3, ``2`` for MLDv2, ``3`` for IGMPv3 in
+    #: Option code -- ``1`` for IGMPv3, ``2`` for MLDv2, ``3`` for IGMPv3 in
     #: IGMPv2 compatibility mode and ``4`` for MLDv2 in MLDv1 compatibility mode.
     code: 'int' = UInt8Field()
     #: Reserved.
@@ -2242,7 +2243,7 @@ class MulticastAcknowledgementOption(Option, code=Enum_Option.Multicast_Acknowle
 
     #: Option code; always ``0``.
     code: 'int' = UInt8Field()
-    #: Status: ``1`` report payload type unsupported, ``2`` requested group
+    #: Status -- ``1`` report payload type unsupported, ``2`` requested group
     #: service unsupported, ``3`` requested group service administratively
     #: prohibited.
     status: 'int' = UInt8Field()

pcapkit/protocols/schema/link/ethernet.py

@@ -34,14 +34,14 @@ def callback_payload(self: 'PayloadField', packet: 'dict[str, Any]') -> 'None':
         subscripting the registry. :attr:`Ethernet.__proto__
         <pcapkit.protocols.link.link.Link.__proto__>` *is*
         :attr:`Link.__proto__ <pcapkit.protocols.link.link.Link.__proto__>`, a
-        class-level :class:`collections.defaultdict`, so reading a missing key
-        inserted it -- every unregistered EtherType a parse saw was recorded as
-        though somebody had registered it, and
-        :meth:`Link.register <pcapkit.protocols.link.link.Link.register>`
-        afterwards reported it as an overwrite. The helper reads the fallback
-        without recording it, and memoises a
-        :class:`~pcapkit.corekit.module.ModuleDescriptor` for a code that really
-        is registered, which this did not.
+        class-level :class:`collections.defaultdict`, so subscripting it with a
+        missing key would insert that key -- every unregistered EtherType a parse
+        saw would be recorded as though somebody had registered it, and
+        :meth:`Link.register <pcapkit.protocols.link.link.Link.register>` would
+        afterwards report it as an overwrite. The helper reads the fallback
+        without recording it, and for a code that really is registered as a
+        :class:`~pcapkit.corekit.module.ModuleDescriptor` it writes the resolved
+        class back, so the import happens once.
 
     """
     from pcapkit.protocols.link.ethernet import Ethernet  # pylint: disable=import-outside-toplevel

pcapkit/protocols/schema/misc/null.py

@@ -11,8 +11,9 @@
 class NoPayload(Schema):
     """Schema for empty payload."""
 
-    # NOTE: We add this method for both type annotation and to mark that this
-    # class accepts no arguments at runtime, since :class:`Schema` explicitly
-    # skipped those whose :attr:`__dict__` is empty :obj:`dict`.
+    # NOTE: Declared both for type annotation and to make this class accept no
+    # arguments at runtime: :func:`schema_final` generates an ``__init__`` only
+    # for a class that does not define one, so this one keeps the generated
+    # ``dict_``-taking constructor from displacing it.
     def __init__(self) -> 'None':  # pylint: disable=super-init-not-called
         pass

pcapkit/protocols/schema/misc/pcapng.py

@@ -81,7 +81,7 @@ class ByteorderTest(TypedDict):
     class ResolutionData(TypedDict):
         """Data for resolution."""
 
-        #: Resolution type flag (0: 10-based, 1: 2-based).
+        #: Resolution type flag (``0`` for 10-based, ``1`` for 2-based).
         flag: int
         #: Resolution value.
         resolution: int
@@ -412,8 +412,8 @@ def bounded_area(length: 'Callable[[dict[str, Any]], int]') -> 'Callable[[dict[s
         The nominal span goes through :func:`nonnegative` first here too. That
         closes a hole in this function's own arithmetic: a ``captured_len`` past
         the end of the block makes the span negative, and ``nominal <= available``
-        below is then *true*, so the negative was returned unclamped and reached
-        a :mod:`struct` template as ``f'{-N}s'``. Measured on 200 Enhanced Packet
+        below is then *true*, so the negative would be returned unclamped and
+        reach a :mod:`struct` template as ``f'{-N}s'``. Measured on 200 Enhanced Packet
         Blocks declaring ``captured_len`` ``0xFFFFFF`` in 8,048 octets.
 
     """
@@ -709,7 +709,7 @@ def __init_subclass__(cls, /, code: 'Optional[Enum_OptionType | Iterable[Enum_Op
                 than ``namespace`` because :meth:`abc.ABCMeta.__new__` names its
                 own fourth parameter ``namespace``, and before Python 3.11 that
                 parameter is positional-or-keyword rather than positional-only --
-                so a class keyword literally called ``namespace`` bound it twice.
+                so a class keyword literally called ``namespace`` binds it twice.
             *args: Arbitrary positional arguments.
             **kwargs: Arbitrary keyword arguments.
 
@@ -944,7 +944,7 @@ def pre_pack(self, packet: 'dict[str, Any]') -> 'None':
     def post_process(self, packet: 'dict[str, Any]') -> 'SectionHeaderBlock':
         """Revise ``schema`` data after unpacking process.
 
-        This method calculate the byteorder value based on
+        This method calculates the byteorder value based on
         the parsed schema.
 
         Args:

pcapkit/protocols/schema/schema.py

@@ -882,8 +882,9 @@ def unpack(cls, data: 'bytes | IO[bytes]',
             When this schema is nested -- unpacked through a
             :class:`~pcapkit.corekit.fields.misc.SchemaField` rather than
             directly -- ``packet`` is not the enclosing schema's own data, but
-            a context built by :func:`~pcapkit.corekit.fields.misc.
-            nested_packet_context`: a name this schema does not itself
+            a context built by
+            :func:`~pcapkit.corekit.fields.misc.nested_packet_context`: a name
+            this schema does not itself
             declare falls through to the enclosing schema, and the enclosing
             schema is also reachable unconditionally under a ``__packet__``
             key. See that function for the exact lookup, write and iteration
@@ -1043,8 +1044,8 @@ class _EnumRegistry(collections.defaultdict):
     The fallback itself is deliberate -- it is how an unknown option, chunk or
     block falls back to its ``Unknown*``/``Unassigned*`` schema -- so this
     subclass keeps returning it and just stops recording it.
-    :meth:`ProtocolBase.\
-    _lookup_registry <pcapkit.protocols.protocol.ProtocolBase._lookup_registry>`
+    :meth:`ProtocolBase._lookup_registry
+    <pcapkit.protocols.protocol.Protocol._lookup_registry>`
     does the same for the protocol-layer ``__proto__`` family.
 
     """
@@ -1059,7 +1060,7 @@ class EnumMeta(SchemaMeta, Generic[_ET]):
     """Meta class to add dynamic support for :class:`EnumSchema`.
 
     This meta class is used to generate necessary attributes for the
-    :class:`SchemaMeta` class. It can be useful to reduce runtime generation
+    :class:`EnumSchema` class. It can be useful to reduce runtime generation
     cost as well as caching already generated attributes.
 
     * :attr:`~EnumSchema.registry` is added to subclasses as an *immutable*
@@ -1239,11 +1240,11 @@ def __init_subclass__(cls, /, code: 'Optional[_ET | Iterable[_ET]]' = None, *arg
 
     @classmethod
     def register(cls, code: '_ET', schema: 'Type[Self]') -> 'None':
-        """Register enumetaion to :attr:`__enum__` mapping.
+        """Register enumeration to :attr:`__enum__` mapping.
 
         Args:
-            code: Enumetaion code.
-            schema: Enumetaion schema.
+            code: Enumeration code.
+            schema: Enumeration schema.
 
         Warns:
             pcapkit.utilities.warnings.RegistryWarning: If ``code`` is already

pcapkit/protocols/schema/transport/tcp.py

@@ -273,7 +273,7 @@ def mptcp_dss_ack_selector(pkt: 'dict[str, Any]') -> 'Field':
         ``struct.error: bad char in struct format``. Nothing here meets that only
         because :class:`Schema
         <pcapkit.protocols.schema.schema.Schema>`'s ``pack`` and ``unpack``
-        special-case ``ConditionalField`` by name and skip the wrapped field
+        special-case ``ConditionalField`` by type and skip the wrapped field
         outright before any ``length`` is read. A ``SwitchField`` needs no such
         special case: its selector always hands back an already-concrete field,
         :class:`~pcapkit.corekit.fields.misc.NoValueField` included, so its