docs: prefer Protocol over ProtocolBase in cross-references, per the owner's #1103 ruling (#2420)

ProtocolBase is the internal hidden API and Protocol is the one exposing the
attributes, so a plain "here is where this member is documented" link targets
Protocol. The owner then refined this: "Use the last documented override." A
docstring describing what a *specific* class overrides has to name the real
ancestor in that class's own chain, which is never Protocol -- Protocol has no
subclasses at all, so ProtocolBase is the last documented override for every
class in the tree.

* Plain documentation links go to Protocol.<member>: the module-level prose and
  `#:` comments in protocol.py, register_protocol/_register_name in
  registry/protocols.py, the `register` Arguments and versionchanged clauses in
  internet.py, link.py, transport.py and sctp.py, and the unrelated-class
  references in sentinels.py, data/data.py, misc/pcap/{frame,header}.py,
  ipv6.py, utilities/config.py, conf.py and the mptcp test.
* Override-describing links go to ProtocolBase.<member>: Internet.{register,
  from_data,_make_payload}, Link.register, Transport.register, IPv6_Ext.protocol,
  the ipv6_ext module docstring and ipv6_ext.rst, the {AH,ESP,HOPOPT,MH}.alias
  MRO sentences, NoPayload.protochain, PCAPNG.{length,packet}, HTTP.from_data and
  HTTPv2's HTTP.unpack. Each of these says "As X", "the base", "the inherited",
  "narrows", "sits between ... in the MRO" or "the guard this shares with", and
  the surrounding sentences already name ProtocolBase.
* The `Raises:` clause of each `register` keeps naming ProtocolBase, unchanged:
  #2316/#1016 ruled that it names the class the guard's `issubclass` actually
  tests while the raised message names Protocol, and
  tests/protocols/test_register_class_guard_unit.py asserts exactly that.
* Class-attribute declaration pointers stay on Protocol -- Protocol.__data__
  (declared on Protocol itself), Protocol.__keywords__ and
  Protocol.__own_make_keywords__ -- since they name where the knob is documented
  rather than a method a class overrides.
* ProtocolBase.__init_subclass__ references are still left alone (l2tpv2.py,
  c_tag.py, protocol-layer-placement.rst): Protocol does override
  __init_subclass__, so those name the base implementation deliberately.

Verified Protocol in no class's __mro__ but its own, and that ProtocolBase
defines and documents every member involved while Protocol declares only
__init_subclass__ and __data__.

AST-structure guard (ast.dump with docstrings stripped) confirms all 12 touched
.py files are prose-only against 27c797d; ipv6_ext.rst carries no code. The
mptcp test, test_docstring_contract.py, test_conventions_doc_claims.py,
test_register_class_guard_unit.py and the docs xref suites pass (91 passed, 22
skipped, 444 subtests), as do tests/protocols, tests/foundation, tests/corekit
and tests/utilities in full (3414 passed, 18 skipped, 60258 subtests).

Author: JarryShaw

docs/source/conf.py

@@ -890,7 +890,7 @@ def sign_wrapped_function(app: 'Sphinx', obj: 'Any', bound_method: bool) -> None
     which for a decorated method is the wrapper. ``sphinx-autodoc-typehints``
     stops unwrapping at a stated ``__signature__``, so it evaluated the
     annotations in the decorator's module. The ``@seekset`` overload of
-    :meth:`~pcapkit.protocols.protocol.ProtocolBase._read_packet` then rendered
+    :meth:`~pcapkit.protocols.protocol.Protocol._read_packet` then rendered
     its return as the bare alias ``Data_Packet``, which only the protocol module
     binds (:issue:`1917`).
 

docs/source/pcapkit/protocols/internet/ipv6_ext.rst

@@ -141,7 +141,7 @@ This class is reached in these ways:
    ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
    have dedicated classes. When one of *those* raises,
    :func:`~pcapkit.corekit.decorators.beholder`
-   (:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
+   (:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
    would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
    ``next`` and crashes the walk as in path 1.
    :meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>` catches

pcapkit/corekit/sentinels.py

@@ -472,7 +472,7 @@ class with no ``__eq__`` of its own does; what it lacks is a readable
 
     The hazard is not theoretical elsewhere: reload staleness is a *tracked*
     defect class here for other constructs -- see
-    :meth:`pcapkit.protocols.protocol.ProtocolBase._lookup_next_layer`'s own
+    :meth:`pcapkit.protocols.protocol.Protocol._lookup_next_layer`'s own
     docstring note on why it declines to memoise a resolved class, and
     :mod:`tests.protocols.test_dispatch_default_resolution_unit`'s own
     ``test_no_stale_class_survives_a_module_reload``, which reloads a module

pcapkit/foundation/registry/protocols.py

@@ -166,11 +166,11 @@ def register_protocol(protocol: 'Type[ProtocolBase]') -> 'None':
     :class:`pcapkit.protocols.application.httpv2.HTTP` -- so they all compete
     for the single key ``'HTTP'``. Registering one of them replaces whichever
     was there, and the replacement is observable through every reader of the
-    registry, e.g. :meth:`ProtocolBase.expand_comp
-    <pcapkit.protocols.protocol.ProtocolBase.expand_comp>`, which resolves a
+    registry, e.g. :meth:`Protocol.expand_comp
+    <pcapkit.protocols.protocol.Protocol.expand_comp>`, which resolves a
     bare protocol name through it. Per :issue:`675` the overwrite is reported,
-    matching :meth:`ProtocolBase.register
-    <pcapkit.protocols.protocol.ProtocolBase.register>` and the other
+    matching :meth:`Protocol.register
+    <pcapkit.protocols.protocol.Protocol.register>` and the other
     overwrite-warning registries.
 
     The guard reads "key present **and** incumbent is a different class" --
@@ -194,8 +194,8 @@ class rather than supplied by a caller, and this function is the funnel
     readers outside this module cannot absorb on their own -- the registry is a
     documented public attribute, and its readers look a bare name up and then
     degrade *silently* on a miss rather than raising, so a re-keying would not
-    announce itself either. :meth:`ProtocolBase.expand_comp
-    <pcapkit.protocols.protocol.ProtocolBase.expand_comp>` falls back to the
+    announce itself either. :meth:`Protocol.expand_comp
+    <pcapkit.protocols.protocol.Protocol.expand_comp>` falls back to the
     name as a plain string, and the ``protocol`` properties on
     :class:`~pcapkit.foundation.reassembly.reassembly.ReassemblyMeta` and
     :class:`~pcapkit.foundation.traceflow.traceflow.TraceFlowMeta` fall back to
@@ -367,7 +367,7 @@ def _register_name(protocol: 'Type[ProtocolBase]', *targets: 'tuple[type, Any]')
     releasing whatever each target code held before, and followed by a lease
     when the write changed the name, so that registering the code back undoes
     it (:issue:`1505`). A name already showing ``protocol`` -- shipped, defined
-    by a :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass, or
+    by a :class:`~pcapkit.protocols.protocol.Protocol` subclass, or
     registered directly -- is not leased, so no restore takes it away; one
     showing it through a lease extends that lease to ``targets``.
 

pcapkit/protocols/application/http.py

@@ -215,7 +215,7 @@ class HTTP(Application[_PT, _ST], Generic[_PT, _ST]):
     #: the 24-octet HTTP/2 connection preface, when :meth:`_guess_version`
     #: identified one and parsed the frame that follows it. They belong to this
     #: packet's header rather than to its payload, so :meth:`read` adds them to
-    #: :attr:`length`; otherwise :meth:`ProtocolBase.__init__ <pcapkit.protocols.protocol.ProtocolBase.__init__>`'s
+    #: :attr:`length`; otherwise :meth:`Protocol.__init__ <pcapkit.protocols.protocol.Protocol.__init__>`'s
     #: ``self._info.__update__(packet=self.packet.payload)`` would slice the
     #: payload from octet 9 of a buffer whose frame starts at octet 24 and report
     #: the tail of the preface as packet payload.
@@ -228,8 +228,8 @@ class HTTP(Application[_PT, _ST], Generic[_PT, _ST]):
     #: :meth:`HTTPv2.make <pcapkit.protocols.application.httpv2.HTTP.make>`
     #: according to that value, so the correct set of names depends on an
     #: argument. :obj:`None` therefore opts out of the construction keyword check
-    #: that :meth:`ProtocolBase.__init__
-    #: <pcapkit.protocols.protocol.ProtocolBase.__init__>` performs; the
+    #: that :meth:`Protocol.__init__
+    #: <pcapkit.protocols.protocol.Protocol.__init__>` performs; the
     #: versioned classes are checked normally when constructed directly.
     __keywords__ = None
 

pcapkit/protocols/application/httpv2.py

@@ -234,7 +234,7 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'
 
             ``length`` is resolved against :func:`len` only for *this*
             method's own check, and the *original* argument -- ``None``
-            included -- is what is forwarded to :meth:`Protocol.unpack
+            included -- is what is forwarded to :meth:`ProtocolBase.unpack
             <pcapkit.protocols.protocol.ProtocolBase.unpack>`. Collapsing
             ``None`` to a concrete ``0`` would change what
             :meth:`Schema.unpack <pcapkit.protocols.schema.schema.Schema.unpack>`'s own
@@ -251,7 +251,7 @@ def unpack(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_HTTP'
         if length is None:
             # ``0 < ... < 9`` rather than ``... < 9``: an exhausted stream
             # (``len(self) == 0``) is left alone, so ``length`` reaches
-            # :meth:`Protocol.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`
+            # :meth:`ProtocolBase.unpack <pcapkit.protocols.protocol.ProtocolBase.unpack>`
             # still ``None`` and its ``prepare`` decorator raises
             # :exc:`StreamEOFError` as documented above; only a *non-empty*
             # short stream is rejected as malformed here.

pcapkit/protocols/data/data.py

@@ -19,7 +19,7 @@ class Data(Info):
     The ``__next_name__``, ``__next_type__`` and ``__short_read__`` keys are
     metadata, listed in :attr:`~pcapkit.corekit.infoclass.Info.__included__`
     and :attr:`~pcapkit.corekit.infoclass.Info.__excluded__`:
-    :meth:`Protocol.from_data <pcapkit.protocols.protocol.ProtocolBase.from_data>`
+    :meth:`Protocol.from_data <pcapkit.protocols.protocol.Protocol.from_data>`
     dispatches the payload on the first two and on nothing else, and cuts a
     short read back on the third. :meth:`to_dict` carries them, so that
     ``from_data(info.to_dict())`` rebuilds as ``from_data(info)`` does, while

pcapkit/protocols/internet/internet.py

@@ -182,7 +182,7 @@ def register(cls, code: 'Enum_TransType', protocol: 'ModuleDescriptor[ProtocolBa
         Arguments:
             code: protocol code as in :class:`~pcapkit.const.reg.transtype.TransType`
             protocol: module descriptor or a
-                :class:`~pcapkit.protocols.protocol.ProtocolBase` subclass
+                :class:`~pcapkit.protocols.protocol.Protocol` subclass
 
         Raises:
             pcapkit.utilities.exceptions.RegistryError: If ``protocol`` is not a

pcapkit/protocols/internet/ipv6.py

@@ -447,7 +447,7 @@ def _exthdr_key(alias: 'str') -> 'str':
         """Key an extension header's info is written under in :class:`Data_IPv6`.
 
         Args:
-            alias: :attr:`~pcapkit.protocols.protocol.ProtocolBase.alias` of
+            alias: :attr:`~pcapkit.protocols.protocol.Protocol.alias` of
                 the extension header's parser.
 
         Returns:

pcapkit/protocols/internet/ipv6_ext.py

@@ -108,7 +108,7 @@ class for that code instead (see the bottom of the module), so dispatch
    ``IPv6-Route``, ``IPv6-Opts``, ``MH``, ``HIP``, ``IPv6-Frag`` and ``AH`` all
    have dedicated classes. When one of *those* raises,
    :func:`~pcapkit.corekit.decorators.beholder`
-   (:meth:`Protocol._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
+   (:meth:`ProtocolBase._import_next_layer <pcapkit.protocols.protocol.ProtocolBase._import_next_layer>`)
    would substitute plain :class:`~pcapkit.protocols.misc.raw.Raw`, which loses
    ``next`` and crashes the walk as in path 1.
    :meth:`IPv6._import_next_layer <pcapkit.protocols.internet.ipv6.IPv6._import_next_layer>`
@@ -299,7 +299,7 @@ def protocol(self) -> 'Optional[Enum_ExtensionHeader] | Optional[str]':
 
         In the *fallback* role (this instance parsed this module's own schema)
         this is **not** the base
-        :attr:`Protocol.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
+        :attr:`ProtocolBase.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`
         meaning ("name of next layer protocol"). On the owner's ruling for
         GitHub issue :issue:`891` it is deliberately repointed at this
         instance's *own* identity, i.e. which header's format it parsed, such as
@@ -324,7 +324,7 @@ class sits between them and
         data model with no such field (``AttributeError``).
 
         The discriminator is the *class-level*
-        :attr:`~pcapkit.protocols.protocol.ProtocolBase.__data__` rather than an
+        :attr:`~pcapkit.protocols.protocol.Protocol.__data__` rather than an
         :func:`isinstance` test on ``self._info``, because a ``make``-only
         instance has no ``_info`` at all. Reading it would turn
         :attr:`ProtocolBase.protocol <pcapkit.protocols.protocol.ProtocolBase.protocol>`,
@@ -510,8 +510,8 @@ def make(self, *,
             there is unioned down the MRO, so every subclass would accept
             these names and drop them. A ``make`` signature can be kept from
             subclasses instead: this class sets
-            :attr:`ProtocolBase.__own_make_keywords__
-            <pcapkit.protocols.protocol.ProtocolBase.__own_make_keywords__>`,
+            :attr:`Protocol.__own_make_keywords__
+            <pcapkit.protocols.protocol.Protocol.__own_make_keywords__>`,
             so a subclass that overrides ``make`` accepts ``len`` or ``data``
             only where its own ``make`` declares it (:issue:`2286`).