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

pcapkit/protocols/__init__.py

@@ -70,7 +70,7 @@
     'RARP', 'DRARP',
 ]
 
-#: dict[str, ~typing.Type[Protocol]]: Protocol registry.
+#: dict[str, ~typing.Type[~pcapkit.protocols.protocol.ProtocolBase]]: Protocol registry.
 __proto__ = {}  # type: dict[str, Type[ProtocolBase]]
 for name in __all__:
     __proto__[name.upper()] = globals()[name]

pcapkit/protocols/application/http.py

@@ -342,7 +342,7 @@ def make(self,
             **kwargs: Arbitrary keyword arguments.
 
         Returns:
-            bytes: Constructed packet data.
+            The header schema the versioned ``make`` constructs.
 
         Raises:
             ProtocolError: If ``version`` is unknown, or if ``preface`` is

pcapkit/protocols/data/misc/raw.py

@@ -14,7 +14,16 @@
 
 @info_final
 class Raw(Protocol):
-    """Raw packet is an unknown protocol."""
+    """Raw packet is an unknown protocol.
+
+    .. versionchanged:: 1.3.3
+
+       ``packet`` is not a field of this class, so its constructor takes
+       ``protocol`` and ``error`` only.
+       :class:`~pcapkit.protocols.protocol.ProtocolBase` sets ``packet`` on
+       the data model of every protocol it constructs.
+
+    """
 
     #: Original enumeration of this protocol.
     protocol: 'Optional[int]'

pcapkit/protocols/protocol.py

@@ -841,9 +841,10 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> '_PT':
             global packet data to underlying methods. This is useful when
             the packet data is not available in the current instance.
 
-            When :meth:`pack` or :meth:`from_schema` has already set
-            :attr:`self.__header__ <Protocol.__header__>`, that schema is
-            kept, unless it still holds raw :obj:`bytes` where parsing its
+            When :attr:`self.__header__ <Protocol.__header__>` is already set,
+            by :meth:`from_schema` or by the :meth:`pack` call that
+            :meth:`__post_init__` makes to construct the instance, that schema
+            is kept, unless it still holds raw :obj:`bytes` where parsing its
             packed octets yields a schema -- e.g. a raw option given to
             ``make()`` -- which :meth:`read` cannot consume. The header is
             then replaced by the parsed one (:issue:`1312`).
@@ -2489,6 +2490,13 @@ class Protocol(ProtocolBase, Generic[_PT, _ST]):
     :doc:`/ext`. The built-in protocol families do not derive from this class
     but from :class:`ProtocolBase`, whose metaclass is :class:`ProtocolMeta`.
 
+    .. versionchanged:: 1.3.0
+
+       The built-in protocol families derive from :class:`ProtocolBase`, so a
+       built-in protocol is not an instance of this class, where every one
+       was; and a subclass is registered in :data:`pcapkit.protocols.__proto__`
+       when it is defined.
+
     """
 
     def __init_subclass__(cls, /, schema: 'Optional[Type[_ST]]' = None,