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

Version directives, 1.1.0-1.4.1 backfill:
- Protocol: versionchanged 1.3.0. The built-in families moved onto
  ProtocolBase, so a built-in protocol is not an instance of Protocol,
  and a Protocol subclass registers itself in pcapkit.protocols.__proto__.
- data.misc.raw.Raw: versionchanged 1.3.3. packet left its fields when the
  base data class took it over, so the constructor takes protocol and
  error only.

Accuracy:
- ProtocolBase.unpack: since #1769, pack() sets __header__ only on the
  call __post_init__ makes during construction, so the note names that
  call and from_schema() rather than pack() in general.
- HTTP.make: Returns said bytes; it returns the versioned make()'s schema.
- pcapkit.protocols.__proto__: the values are ProtocolBase subclasses,
  and the built-in ones are not Protocol subclasses.

AST guard identical on all four files; tests/project and the pack, HTTP
and docstring-contract tests pass.

Refs #1103

Author: JarryShaw

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,