docs(protocols): second whole-repo pass over link and transport (#1103)

pcapkit/protocols/data/transport/tcp.py

@@ -223,7 +223,14 @@ def __init__(self, kind: 'OptionNumber', length: 'int', data: 'bytes') -> 'None'
 
 @info_final
 class Timestamps(Option):
-    """Data model for TCP timestamp option."""
+    """Data model for TCP timestamp option.
+
+    .. versionchanged:: 1.1.0
+
+       Renamed from ``Timestamp``, which :mod:`pcapkit.protocols.data`
+       exported as ``TCP_Timestamp``; the export is ``TCP_Timestamps``.
+
+    """
 
     #: Timestamp value.
     timestamp: 'int'
@@ -244,7 +251,16 @@ def __init__(self, kind: 'OptionNumber', length: 'int') -> 'None': ...  # pylint
 
 @info_final
 class PartialOrderServiceProfile(Option):
-    """Data model for TCP partial order connection service profile option."""
+    """Data model for TCP partial order connection service profile option.
+
+    .. versionchanged:: 1.1.0
+
+       Renamed from ``PartialOrderConnectionProfile``, which
+       :mod:`pcapkit.protocols.data` exported as
+       ``TCP_PartialOrderConnectionProfile``; the export is
+       ``TCP_PartialOrderServiceProfile``.
+
+    """
 
     #: Start flag.
     start: 'bool'

pcapkit/protocols/link/link.py

@@ -139,6 +139,13 @@ def register(cls, code: 'Enum_EtherType', protocol: 'ModuleDescriptor[ProtocolBa
                 guard this shares with ``register_protocol``, and for the
                 shipped descriptor a restore puts back (:issue:`1504`).
 
+        .. versionchanged:: 1.3.0
+
+           Takes the protocol as one ``protocol`` argument, a
+           :class:`~pcapkit.corekit.module.ModuleDescriptor` or a
+           :class:`~pcapkit.protocols.protocol.Protocol` subclass, in place of
+           the ``module`` and ``class_`` names.
+
         """
         incumbent = cls.__proto__.get(code)
         entry = cls._next_layer_entry(code, protocol)

pcapkit/protocols/schema/transport/tcp.py

@@ -522,7 +522,14 @@ def __init__(self, kind: 'Enum_Option', length: 'int', data: 'bytes') -> 'None':
 
 @schema_final
 class Timestamps(Option, code=Enum_Option.Timestamps):
-    """Header schema for TCP timestamps option."""
+    """Header schema for TCP timestamps option.
+
+    .. versionchanged:: 1.1.0
+
+       Renamed from ``Timestamp``, which :mod:`pcapkit.protocols.schema`
+       exported as ``TCP_Timestamp``; the export is ``TCP_Timestamps``.
+
+    """
 
     #: Timestamp value.
     value: 'int' = UInt32Field()
@@ -543,7 +550,16 @@ def __init__(self, kind: 'Enum_Option', length: 'int') -> 'None': ...
 
 @schema_final
 class PartialOrderServiceProfile(Option, code=Enum_Option.Partial_Order_Service_Profile):
-    """Header schema for TCP partial order connection service profile option."""
+    """Header schema for TCP partial order connection service profile option.
+
+    .. versionchanged:: 1.1.0
+
+       Renamed from ``PartialOrderConnectionProfile``, which
+       :mod:`pcapkit.protocols.schema` exported as
+       ``TCP_PartialOrderConnectionProfile``; the export is
+       ``TCP_PartialOrderServiceProfile``.
+
+    """
 
     #: Profile data.
     profile: 'POCProfile' = BitField(length=1, namespace={
@@ -720,7 +736,17 @@ def post_process(self, packet: 'dict[str, Any]') -> 'MPTCP':
 
 
 class MPTCP(EnumSchema[Enum_MPTCPOption]):
-    """Header schema for Multipath TCP options."""
+    """Header schema for Multipath TCP options.
+
+    .. versionchanged:: 1.1.0
+
+       An :class:`~pcapkit.protocols.schema.schema.EnumSchema` keyed on
+       :class:`~pcapkit.const.tcp.mp_tcp_option.MPTCPOption` rather than a
+       subclass of :class:`~pcapkit.protocols.schema.transport.tcp.Option`,
+       which registers :class:`~pcapkit.protocols.schema.transport.tcp._MPTCP`
+       under ``Multipath_TCP`` instead.
+
+    """
 
     __enum__: 'DefaultDict[Enum_MPTCPOption, Type[MPTCP]]' = collections.defaultdict(lambda: MPTCPUnknown)
 

pcapkit/protocols/transport/transport.py

@@ -110,6 +110,13 @@ def register(cls, code: 'int', protocol: 'ModuleDescriptor[ProtocolBase] | Type[
             ``register_apptype`` reaches this method once per protocol and
             inspects two different registries, so it cannot warn spuriously.
 
+        .. versionchanged:: 1.3.0
+
+           Takes the protocol as one ``protocol`` argument, a
+           :class:`~pcapkit.corekit.module.ModuleDescriptor` or a
+           :class:`~pcapkit.protocols.protocol.Protocol` subclass, in place of
+           the ``module`` and ``class_`` names.
+
         """
         if cls is Transport:
             raise UnsupportedCall(f'{cls.__name__} is an abstract class')