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

pcapkit/protocols/data/__init__.py

@@ -64,7 +64,7 @@
     # Open Shortest Path First
     'OSPF', 'OSPF_CrytographicAuthentication',
 
-    # 802.1Q Customer VLAN Tag Type
+    # 802.1Q/802.1ad VLAN Tag Types
     'VLAN', 'VLAN_TCI',
 
     # Authentication Header

pcapkit/protocols/data/application/httpv2.py

@@ -258,7 +258,7 @@ def __init__(self, length: 'int', type: 'Frame', flags: 'Optional[Flags]', sid:
 
 @info_final
 class WindowUpdateFrame(HTTP):
-    """Data moddel for HTTP/2 ``WINDOW_UPDATE`` frame."""
+    """Data model for HTTP/2 ``WINDOW_UPDATE`` frame."""
 
     #: Flags.
     flags: 'Literal[None]'

pcapkit/protocols/data/application/ospf.py

@@ -18,7 +18,7 @@
 
 @info_final
 class CrytographicAuthentication(Data):
-    """Data model for OSPF crytographic authentication."""
+    """Data model for OSPF cryptographic authentication."""
 
     #: Key ID.
     key_id: 'int'

pcapkit/protocols/data/internet/hip.py

@@ -225,9 +225,9 @@ class SolutionParameter(Parameter):
     #: Reserved octet -- "zero when sent, ignored when received"
     #: (:rfc:`7401#section-5.2.5`, and :rfc:`5201#section-5.2.5` identically).
     #: Carried verbatim rather than interpreted, so that re-serialising a parsed
-    #: parameter reproduces the octet it arrived with. It used to be read as a
-    #: ``PUZZLE`` ``Lifetime``, which only :rfc:`7401#section-5.2.4` defines, and
-    #: the conformant ``0x00`` then could not be re-serialised at all. See :issue:`654`.
+    #: parameter reproduces the octet it arrived with. It is not a ``Lifetime``:
+    #: only ``PUZZLE`` has one (:rfc:`7401#section-5.2.4`), and reading it as one
+    #: would leave the conformant ``0x00`` impossible to re-serialise. See :issue:`654`.
     reserved: 'int'
     #: Solution data.
     opaque: 'bytes'

pcapkit/protocols/data/internet/hopopt.py

@@ -342,7 +342,7 @@ class IPDFFOption(Option):
 
     #: Version.
     version: 'int'
-    #:Flags.
+    #: Flags.
     flags: 'DFFFlags'
     #: Sequence number.
     seq: 'int'

pcapkit/protocols/data/internet/ipv4.py

@@ -49,7 +49,7 @@ class ToSField(Data):
     """Data model for IPv4 ToS fields.
 
     Important:
-        Due to the preserved keyword conflict, please use :meth:`from_dict`
+        Due to the reserved keyword conflict, please use :meth:`from_dict`
         to create an instance of this data model.
 
     """
@@ -68,7 +68,7 @@ class ToSField(Data):
     def __new__(cls, *args: 'Any', **kwargs: 'Any') -> 'ToSField':
         self = super().__new__(cls, *args, **kwargs)
 
-        # NOTE: We cannot define ``del`` due to preserved keyword conflict.
+        # NOTE: We cannot define ``del`` due to reserved keyword conflict.
         # Thus, we directly inject the information into the annotations.
         cls.__annotations__['del'] = ToSDelay
 
@@ -118,6 +118,7 @@ class IPv4(Protocol):
     dst: 'IPv4Address'
 
     if TYPE_CHECKING:
+        #: Options, present only when the header carries any.
         options: 'OrderedMultiDict[OptionNumber, Option]'
 
         def __init__(self, version: 'Literal[4]', hdr_len: 'int', tos: 'ToSField', len: 'int', id: 'int', flags: 'Flags', offset: 'int', ttl: 'timedelta', protocol: 'TransType', checksum: 'bytes', src: 'IPv4Address', dst: 'IPv4Address') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
@@ -137,7 +138,7 @@ class OptionType(Data):
     def __new__(cls, *args: 'Any', **kwargs: 'Any') -> 'OptionType':
         self = super().__new__(cls, *args, **kwargs)
 
-        # NOTE: We cannot define ``class`` due to preserved keyword conflict.
+        # NOTE: We cannot define ``class`` due to reserved keyword conflict.
         # Thus, we directly inject the information into the annotations.
         cls.__annotations__['class'] = OptionClass
 
@@ -302,7 +303,7 @@ class TROption(Option):
     """Data model for IPv4 Traceroute (``TR``) option.
 
     Important:
-        Due to the preserved keyword conflict, please use :meth:`from_dict`
+        Due to the reserved keyword conflict, please use :meth:`from_dict`
         to create an instance of this data model.
 
     """
@@ -313,12 +314,13 @@ class TROption(Option):
     outbound: 'int'
     #: Return hop count.
     #return: 'int'
+    #: Originator IP address.
     originator: 'IPv4Address'
 
     def __new__(cls, *args: 'Any', **kwargs: 'Any') -> 'TROption':
         self = super().__new__(cls, *args, **kwargs)
 
-        # NOTE: We cannot define ``return`` due to preserved keyword conflict.
+        # NOTE: We cannot define ``return`` due to reserved keyword conflict.
         # Thus, we directly inject the information into the annotations.
         cls.__annotations__['return'] = int
 

pcapkit/protocols/data/internet/ipv6.py

@@ -25,7 +25,7 @@ class IPv6(Protocol):
     """Data model for Internet Protocol version 6.
 
     Important:
-        Due to the preserved keyword conflict, please use :meth:`from_dict`
+        Due to the reserved keyword conflict, please use :meth:`from_dict`
         to create an instance of this data model.
 
     """
@@ -60,7 +60,7 @@ class IPv6(Protocol):
     def __new__(cls, *args: 'Any', **kwargs: 'Any') -> 'IPv6':
         self = super().__new__(cls, *args, **kwargs)
 
-        # NOTE: We cannot define ``class`` due to preserved keyword conflict.
+        # NOTE: We cannot define ``class`` due to reserved keyword conflict.
         # Thus, we directly inject the information into the annotations.
         cls.__annotations__['class'] = int
 

pcapkit/protocols/data/internet/ipv6_ext.py

@@ -27,9 +27,9 @@ class IPv6_Ext(Protocol):
     #: The extension header this instance stands in for -- the numeric code
     #: the caller dispatched on, resolved to its
     #: :class:`~pcapkit.const.ipv6.extension_header.ExtensionHeader` member.
-    #: :data:`None` when ``alias`` named no such member (:meth:`read
-    #: <pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.read>`
-    #: sets it so on a lookup miss, and the class property at
+    #: :data:`None` when ``alias`` was not given or named no such member
+    #: (:meth:`read <pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.read>`
+    #: sets it so in both cases, and the class property at
     #: :attr:`~pcapkit.protocols.internet.ipv6_ext.IPv6_Ext.protocol`
     #: is typed to match).
     protocol: 'Optional[ExtensionHeader]'

pcapkit/protocols/data/internet/ipv6_opts.py

@@ -358,7 +358,7 @@ class IPDFFOption(Option):
 
     #: Version.
     version: 'int'
-    # :Flags.
+    #: Flags.
     flags: 'DFFFlags'
     #: Sequence number.
     seq: 'int'

pcapkit/protocols/data/internet/mh.py

@@ -174,7 +174,7 @@ def __init__(self, next: 'TransType', length: 'int', type: 'Packet', chksum: 'by
 
 @info_final
 class HomeTestInitMessage(MH):
-    """Data modelf for MH Home Test Init (HoTI) message type."""
+    """Data model for MH Home Test Init (HoTI) message type."""
 
     #: Home init cookie.
     cookie: 'bytes'
@@ -248,7 +248,7 @@ class BindingUpdateMessage(MH):
     ack: 'bool'
     #: home registration flag.
     home: 'bool'
-    #: Link-local address compability flag.
+    #: Link-local address compatibility flag.
     lla_compat: 'bool'
     #: Key management mobility capability flag.
     key_mngt: 'bool'
@@ -855,7 +855,7 @@ class CGAParameter(Data):
     prefix: 'int'
     #: Collision count.
     collision_count: 'int'
-    #: Publick key (ASN.1 encoded).
+    #: Public key (ASN.1 encoded).
     public_key: 'bytes'
     #: Extension fields.
     extensions: 'OrderedMultiDict[Enum_CGAExtension, CGAExtension]'

pcapkit/protocols/data/link/__init__.py

@@ -9,7 +9,7 @@
 # Ethernet Protocol
 from pcapkit.protocols.data.link.ethernet import Ethernet
 
-# 802.1Q Customer VLAN Tag Type
+# 802.1Q/802.1ad VLAN Tag Types
 from pcapkit.protocols.data.link.vlan import TCI as VLAN_TCI
 from pcapkit.protocols.data.link.vlan import VLAN
 
@@ -20,6 +20,6 @@
     # Ethernet Protocol
     'Ethernet',
 
-    # 802.1Q Customer VLAN Tag Type
+    # 802.1Q/802.1ad VLAN Tag Types
     'VLAN', 'VLAN_TCI',
 ]

pcapkit/protocols/data/misc/null.py

@@ -12,7 +12,8 @@ class NoPayload(Protocol):
     """No-payload packet is an empty packet."""
 
     # NOTE: We add this method for both type annotation and to mark that this
-    # class accepts no arguments at runtime, since :class:`Info` explicitly
-    # skipped those whose :attr:`__annotations__` is empty :obj:`dict`.
+    # class accepts no arguments at runtime, since for a class with no
+    # annotations :class:`Info` generates an ``__init__`` taking any mapping
+    # and keywords.
     def __init__(self) -> 'None':  # pylint: disable=super-init-not-called
         pass

pcapkit/protocols/data/misc/pcapng.py

@@ -785,7 +785,7 @@ def __init__(self, entries: 'OrderedMultiDict[WireGuardKeyLabel, bytes]') -> 'No
 
 @info_final
 class ZigBeeNWKKey(DSBSecrets):
-    """Data model for ZigBEE NWK Key and ZigBee PANID secrets data."""
+    """Data model for ZigBee NWK Key and ZigBee PANID secrets data."""
 
     #: AES-128 NKW key.
     nwk_key: 'bytes'
@@ -798,7 +798,7 @@ def __init__(self, nwk_key: 'bytes', pan_id: 'int') -> 'None': ...
 
 @info_final
 class ZigBeeAPSKey(DSBSecrets):
-    """Data model for ZigBEE APS Key secrets data."""
+    """Data model for ZigBee APS Key secrets data."""
 
     #: AES-128 APS key.
     aps_key: 'bytes'

pcapkit/protocols/data/transport/tcp.py

@@ -440,7 +440,7 @@ class MPTCPJoinSYN(MPTCPJoin):
     addr_id: 'int'
     #: Receiver's token.
     token: 'int'
-    #: Sendder's random number.
+    #: Sender's random number.
     nonce: 'int'
 
     if TYPE_CHECKING:
@@ -457,7 +457,7 @@ class MPTCPJoinSYNACK(MPTCPJoin):
     addr_id: 'int'
     #: Sender's truncated HMAC.
     hmac: 'bytes'
-    #: Sendder's random number.
+    #: Sender's random number.
     nonce: 'int'
 
     if TYPE_CHECKING: