docs(docs): sweep the Sphinx pages for stale claims, toctree order and markup (#1103)

docs/source/conf.py

@@ -88,8 +88,7 @@
 #
 # These are deliberately opt-in per site rather than an automatic ``#NNN`` rule,
 # because no digit-keyed pattern can tell a citation from a packet-diagram label:
-# ``#\d{3}`` will miss four-digit numbers once the tracker reaches them -- there are
-# none yet -- and already misses 17 two-digit ones, while ``#\d+`` catches the 45
+# ``#\d{3}`` misses every two- and four-digit number, while ``#\d+`` catches the 45
 # one-digit RFC diagram labels across ``pcapkit/protocols/internet/hip.py`` (36),
 # ``pcapkit/protocols/transport/sctp.py`` (7) and
 # ``pcapkit/protocols/schema/internet/hip.py`` (2) -- ``DH GROUP ID #1``,
@@ -98,8 +97,8 @@
 #
 # The caption is ``#%s`` for both ``:issue:`` and ``:pr:`` so that converting a bare
 # citation or an explicit link changes the markup and not the rendered text. A
-# citation written as an inline literal is the one exception: it rendered as monospace
-# and now renders as a link in body font. The two roles exist separately because the
+# citation written as an inline literal is the one exception: converting it turns
+# monospace into a link in body font. The two roles exist separately because the
 # issue-versus-pull-request distinction is itself a documented convention (see
 # ``contributing/conventions/documentation.rst``), and a single role would flatten it
 # in the source even though GitHub redirects between ``/issues/NNN`` and ``/pull/NNN``
@@ -322,12 +321,11 @@ def bind_type_checking_names(app: 'Sphinx') -> None:
     annotations resolvable also makes a malformed one **fatal**. A quoted
     annotation with stray whitespace inside the quotes -- ``rank: ' int'``, the
     space that belongs after the colon typed one character late -- is meaningless
-    to a type checker and was previously harmless here, because these annotations
-    failed earlier with :exc:`NameError`, which
-    :func:`sphinx.util.typing.get_type_hints` catches. Now they resolve, and Python
-    3.14's :mod:`annotationlib` rejects the leading space with a
-    :exc:`SyntaxError` that :func:`~sphinx.util.typing.get_type_hints` does *not*
-    catch, so it aborts the whole build. Two such annotations existed and both are
+    to a type checker, and is harmless while the annotation fails earlier with
+    :exc:`NameError`, which :func:`sphinx.util.typing.get_type_hints` catches.
+    Once it resolves, Python 3.14's :mod:`annotationlib` rejects the leading space
+    with a :exc:`SyntaxError` that :func:`~sphinx.util.typing.get_type_hints` does
+    *not* catch, so it aborts the whole build. Two such annotations existed and both are
     fixed at source; a third would stop the build rather than be worked around
     here, which is the right way round for a typo.
 

docs/source/contributing/conventions/index.rst

@@ -8,17 +8,17 @@ House Conventions
    automated contributor would otherwise have to rediscover by reading a closed
    issue thread. Each ruling names where it was settled.
 
-   :ref:`mint-criterion` and :ref:`registry-protocol` govern
-   :mod:`pcapkit.const`, which is where the settled questions have mostly
-   arisen. :ref:`sentinel-convention` governs :mod:`pcapkit.corekit`,
-   :ref:`extension-header-subclassing` a protocol class hierarchy,
-   :ref:`protocol-layer-placement` which subpackage a dissector belongs in,
-   :ref:`utilities-or-corekit` which of :mod:`pcapkit.utilities` and
-   :mod:`pcapkit.corekit` a support module belongs in,
-   :ref:`process` the repository rather than any of its code,
+   :ref:`mint-criterion` governs :mod:`pcapkit.const`, which is where the
+   settled questions have mostly arisen, :ref:`sentinel-convention`
+   :mod:`pcapkit.corekit`, and :ref:`registry-protocol` :mod:`pcapkit.const`
+   again. :ref:`extension-header-subclassing` governs a protocol class
+   hierarchy, :ref:`protocol-layer-placement` which subpackage a dissector
+   belongs in, :ref:`process` the repository rather than any of its code,
    :ref:`documentation` the prose itself -- on these pages and in the API
-   reference -- rather than any code at all, and :ref:`test-coverage` what the
-   test suite has to prove.
+   reference -- rather than any code at all, :ref:`test-coverage` what the
+   test suite has to prove, and :ref:`utilities-or-corekit` which of
+   :mod:`pcapkit.utilities` and :mod:`pcapkit.corekit` a support module belongs
+   in.
 
    **A ruling that stays in its thread is a ruling that gets rediscovered.** So
    when a question is answered in a way the code cannot express on its own -- a

docs/source/contributing/conventions/process.rst

@@ -42,7 +42,7 @@ once:
    they are on demand -- one extra at a time, ``pip install pypcapkit[Scapy]`` and so
    on. This holds however easy they are to install, and it is what the ruling
    changed: four of them used to be in ``all``.
-*  **``PyPCAP`` and ``PCAP_CT`` were already excluded for installability**, which the
+*  ``PyPCAP`` **and** ``PCAP_CT`` **were already excluded for installability**, which the
    ruling leaves untouched. ``pypcap`` is an sdist-only C extension needing a
    compiler and the libpcap development files; ``pcap-ct`` and ``libpcap`` are
    published only as pre-releases, and ``all`` should not be how somebody acquires a
@@ -317,7 +317,7 @@ carrying it are that kind:
    of the numbering, with nothing labelled at all between them and that change. Three
    of those seven are distribution rollups, each also carrying ``release``; the other
    four are early ``refactor``/``feat`` work from before the project stabilised. On
-   issues it is sparser still, appearing only from :issue:`775` up. So ``breaking``'s
+   issues it is sparser still, appearing only from :issue:`719` up. So ``breaking``'s
    absence on an old pull request is weak evidence at best. The current figures, rather
    than these:
 

docs/source/contributing/conventions/protocol-layer-placement.rst

@@ -184,14 +184,17 @@ protocol number is refused.
 
 **Swapping** :class:`~pcapkit.protocols.link.link.Link` **for**
 :class:`~pcapkit.protocols.application.application.Application` **is not name-for-name.**
-Counting the names each class body sets, whether new or overriding
-:class:`~pcapkit.protocols.protocol.ProtocolBase`'s, ``Link`` has
-seven -- ``__data__``, ``__layer__``, ``__proto__``, ``__schema__``,
-``_read_protos``, ``register`` and ``layer`` -- and ``Application`` eight: the four
-they share (``__data__``, ``__layer__``, ``__schema__``, ``layer``) plus
-``__index__``, ``__post_init__``, ``_decode_next_layer`` and ``_import_next_layer``.
-``Link`` overrides three of those that ``Application`` does not -- ``__proto__``,
-``register`` and ``_read_protos`` -- but all three also exist on ``ProtocolBase``, so
+Counting the names in each class's own namespace, whether new or overriding
+:class:`~pcapkit.protocols.protocol.ProtocolBase`'s, and including those
+``ProtocolBase.__init_subclass__`` sets there, ``Link`` has
+ten -- ``__data__``, ``__layer__``, ``__post_init__``, ``__proto__``,
+``__schema__``, ``_read_protos``, ``_shipped_proto``, ``from_data``, ``register`` and
+``layer`` -- and ``Application`` nine: the six they share (``__data__``, ``__layer__``,
+``__post_init__``, ``__schema__``, ``from_data``, ``layer``) plus ``__index__``,
+``_decode_next_layer`` and ``_import_next_layer``.
+``Link`` overrides four of those that ``Application`` does not -- ``__proto__``,
+``register``, ``_read_protos`` and ``_shipped_proto``, the last set because ``Link``
+defines its own ``__proto__`` -- but all four also exist on ``ProtocolBase``, so
 the strict difference ``Link`` minus ``Application`` minus ``ProtocolBase`` is **empty**
 and every one of them still resolves on ``OSPF``. What changes is which registry it
 resolves *to*: ``OSPF.__proto__`` is ``ProtocolBase.__proto__`` rather than

docs/source/contributing/conventions/registry-protocol.rst

@@ -199,8 +199,8 @@ instance nor the type::
    TypeError: super(type, obj): obj must be an instance or subtype of type
 
 Both forms share ``instance or subtype of type``, which is the only part of the
-message anything here relies on -- pinning either full sentence would pass on two of
-the five supported versions and fail on the other three.
+message anything here relies on -- pinning either full sentence would fail on two or
+three of the five supported versions.
 
 Two corollaries worth stating, because the obvious summary of this is wrong in both
 directions. ``RuntimeError: super(): no arguments`` is a *different* failure, raised

docs/source/contributing/conventions/test-coverage.rst

@@ -7,8 +7,10 @@ The pages before this one rule on the library, the repository and the prose. Thi
 rules on what the test suite has to prove, and what a change has to bring to it. The
 owner set the direction on :issue:`1203`, paraphrased here as on the other pages: every
 round trip the library offers must pass and match exactly, the tests must cover all of
-them, and the rules belong on a page rather than in review threads. :issue:`1202` tracks
-extending round-trip coverage to the paths that do not have it yet.
+them, and the rules belong on a page rather than in review threads. :issue:`1202`
+extended round-trip coverage past the registries, to the :mod:`pcapkit.corekit` fields,
+schemas and ``Info``, the :mod:`pcapkit.foundation` reassembly, flow tracing, engines and
+registries, and the output formats.
 
 Round-Trip Invariants
 ~~~~~~~~~~~~~~~~~~~~~
@@ -42,18 +44,16 @@ The rules those tables carry:
 
 *  **Every registered code has a case.** ``test_every_registered_code_has_a_case``
    fails otherwise. The option suite's ``SKIP`` table is the only exit, and each of its
-   five entries states why a case would assert nothing: TCP's ``End_of_Option_List``
-   and ``No_Operation`` are padding that ``_make_tcp_options`` drops, ``Multipath_TCP``
-   is the envelope of the ``tcp-mptcp`` family and would duplicate one of its subtypes,
-   and ``PadN`` under HOPOPT and IPv6-Opts emits the same option-less header as
-   ``Pad1``. A code that fails is never skipped.
+   three entries states why a case would assert nothing: ``Multipath_TCP`` is the
+   envelope of the ``tcp-mptcp`` family and would duplicate one of its subtypes, and
+   ``PadN`` under HOPOPT and IPv6-Opts emits the same option-less header as ``Pad1``.
+   A code that fails is never skipped.
 *  **A failing case is an entry, never a changed argument.** An ``EXPECTED_FAILURES``
    entry records the status, a failure-detail fragment narrow enough to match one
    site, and the defect: the ``file:line`` that causes it and the issue that tracks it.
    Routing a case around a defect hides it: the generator's ``HIP_COPIES`` once put two
    parameters in every HIP packet, so the unrepresentable length of a lone one
-   (:issue:`651`) was never constructed. Entries older than this page name the
-   ``file:line`` alone, and :issue:`1202` is where they gain their issue.
+   (:issue:`651`) was never constructed.
    ``KNOWN_DEGRADED`` entries have a different shape -- a fragment and a reason -- and
    its two record why the probe's placeholder payload cannot reach the target, not a
    defect to fix, so the ``file:line``-and-issue rule does not apply to them.
@@ -180,5 +180,5 @@ above:
      - Unit tests under :file:`tests/dumpkit/` asserting the output exactly, and a case
        in :file:`tests/integration/test_output_formats.py` for the file that lands on
        disk. That a format :mod:`pcapkit` also reads, such as PCAP, reproduces its
-       input byte for byte is the target :issue:`1202` tracks; nothing asserts it
-       yet.
+       input byte for byte is asserted over every sample capture by
+       :file:`tests/dumpkit/test_capture_dump_runtime.py` (:issue:`1202`).