docs: add a glossary for terms with several meanings (#1949)

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

@@ -8,9 +8,10 @@ rules on what the test suite has to prove, and what a change has to bring to it.
 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`
-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.
+extended round-trip coverage past the :term:`registries <registry>`, to the
+:mod:`pcapkit.corekit` fields, schemas and ``Info``, the :mod:`pcapkit.foundation`
+reassembly, flow tracing, engines and :term:`registries <registry>`, and the output
+formats.
 
 Round-Trip Invariants
 ~~~~~~~~~~~~~~~~~~~~~

docs/source/ext.rst

@@ -101,6 +101,8 @@ The protocol classes :mod:`pcapkit` ships:
 |                                                                  | :class:`pcapkit.protocols.misc.null.NoPayload`                                                       |
 +------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
 
+.. _ext-new-protocol:
+
 New Protocol
 ------------
 

docs/source/glossary.rst

@@ -0,0 +1,59 @@
+Glossary
+========
+
+Some words in these docs carry more than one meaning. Each entry says which
+sense applies where, and links to the page that explains it.
+
+.. glossary::
+
+   data model
+       A :class:`~pcapkit.protocols.data.data.Data` subclass, or an instance of
+       one: a protocol's fields as parsed values, which :attr:`Protocol.info
+       <pcapkit.protocols.protocol.Protocol.info>` returns, as against the raw
+       octets of :attr:`Protocol.data <pcapkit.protocols.protocol.Protocol.data>`.
+       Its base, :class:`~pcapkit.corekit.infoclass.Info`, models the library's
+       other records too, such as the reassembly ones; :ref:`ext-new-protocol`
+       explains data models.
+
+   default engine
+       The engine that ``engine='default'`` (also spelled ``'pcapkit'``) selects,
+       and the one an unknown or unavailable engine falls back to: the built-in
+       :class:`~pcapkit.foundation.engines.pcap.PCAP` and
+       :class:`~pcapkit.foundation.engines.pcapng.PCAPNG` readers, picked by the
+       input's magic number (:doc:`pcapkit/foundation/engines/builtin`).
+
+   info
+       On a protocol, :attr:`Protocol.info
+       <pcapkit.protocols.protocol.Protocol.info>`: its :term:`data model`, stored
+       in the enclosing layer's data model under :attr:`Protocol.info_name
+       <pcapkit.protocols.protocol.Protocol.info_name>`
+       (:doc:`pcapkit/protocols/protocol`). Elsewhere, an
+       :class:`~pcapkit.corekit.infoclass.Info` instance, such as the
+       :term:`reasm.tcp.packet` record that reassembly takes as ``info``
+       (:doc:`pcapkit/corekit/infoclass`).
+
+   registry
+       One of these, told apart by context:
+
+       * an upstream registry, such as an IANA protocol number registry, that
+         the crawlers fetch (:doc:`pcapkit/vendor/index`);
+       * the :mod:`pcapkit.const` enumeration generated from one, such as
+         :class:`~pcapkit.const.reg.ethertype.EtherType`
+         (:doc:`pcapkit/const/index`);
+       * a dispatch table from a code or name to the class that handles it,
+         such as :attr:`Protocol.__proto__
+         <pcapkit.protocols.protocol.Protocol.__proto__>` or
+         :attr:`Extractor.__engine__
+         <pcapkit.foundation.extraction.Extractor.__engine__>`, and the
+         registration functions that write to one
+         (:doc:`pcapkit/foundation/registry`);
+       * :attr:`EnumMeta.registry
+         <pcapkit.protocols.schema.schema.EnumMeta.registry>`, the mapping from
+         an enumeration member to the :term:`schema` that parses it.
+
+   schema
+       A :class:`~pcapkit.protocols.schema.schema.Schema` subclass, which lays
+       out a protocol header's fields as they sit on the wire, or an instance of
+       one: the header as read or built, which :attr:`Protocol.schema
+       <pcapkit.protocols.protocol.Protocol.schema>` returns. It is not the
+       :term:`data model`; :ref:`ext-new-protocol` explains the pair.

docs/source/index.rst

@@ -33,6 +33,7 @@ analysis.
 
    ext
    demo
+   glossary
    changelog
 
 .. toctree::

docs/source/pcapkit/const/index.rst

@@ -11,7 +11,7 @@ automatically generated from the :mod:`pcapkit.vendor` module.
 Unrecognised Values
 -------------------
 
-Nearly every registry below departs from :mod:`enum` in one deliberate way, and it
+Nearly every :term:`registry` below departs from :mod:`enum` in one deliberate way, and it
 is the behaviour to know about before using any of them: looking one up by a value
 it does not define does **not** raise. Its ``_missing_`` override returns a
 member-like object for a value inside the registry's valid range, named for the

docs/source/pcapkit/foundation/engines/3rdparty.rst

@@ -294,7 +294,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    extraction. :meth:`PCAP_CT.unsupported_reason
    <pcapkit.foundation.engines.pcap_ct.PCAP_CT.unsupported_reason>` detects it and
    reports it as an ordinary "engine unavailable", so the extraction falls back to
-   the default engine with a warning naming the missing library.
+   the :term:`default engine` with a warning naming the missing library.
 
 .. warning::
 

docs/source/pcapkit/foundation/engines/builtin.rst

@@ -2,6 +2,8 @@
 Built-in Engines
 ================
 
+Together, the readers below are the :term:`default engine`.
+
 PCAP Support
 ============
 

docs/source/pcapkit/foundation/engines/index.rst

@@ -219,7 +219,7 @@ installed.** Pick on availability, not on features.
    system library at all ``import pcap`` raises :exc:`OSError` rather than
    :exc:`ImportError`; :meth:`PCAP_CT.unsupported_reason
    <pcapkit.foundation.engines.pcap_ct.PCAP_CT.unsupported_reason>` catches that and turns
-   it into an ordinary fall back to the default engine, instead of the hard error it would
+   it into an ordinary fall back to the :term:`default engine`, instead of the hard error it would
    otherwise be.
 
 **The two distributions collide, so install exactly one.** Both own the top-level

docs/source/pcapkit/foundation/extraction.rst

@@ -15,8 +15,8 @@ and extracts parameters from a PCAP file.
    :class:`pcapkit.foundation.engines.pypcap.PyPCAP` (``engine='pypcap'``),
    :class:`pcapkit.foundation.engines.pcap_ct.PCAP_CT` (``engine='pcap_ct'``)
    and :class:`pcapkit.foundation.engines.pypcapfile.PyPCAPFile`
-   (``engine='pypcapfile'``). Each supports less than the ``default``
-   engine does; :doc:`engines/index` tabulates the gaps, and the
+   (``engine='pypcapfile'``). Each supports less than the
+   :term:`default engine` does; :doc:`engines/index` tabulates the gaps, and the
    :doc:`main page <../../index>` documents their installation prerequisites.
 
 .. autoclass:: pcapkit.foundation.extraction.Extractor

docs/source/pcapkit/protocols/protocol.rst

@@ -123,7 +123,7 @@ VLAN tags and IPv6 extension headers alike. What follows is kept as
 :class:`~pcapkit.protocols.misc.raw.Raw`, with one
 :exc:`~pcapkit.utilities.warnings.ProtocolWarning` (:issue:`1610`), and is
 marked :attr:`~pcapkit.protocols.protocol.Protocol._past_layer_limit`, so the
-default engine's TCP reassembly and flow tracing do not read a TCP segment
+:term:`default engine`'s TCP reassembly and flow tracing do not read a TCP segment
 there back out, as they do one the TCP parser rejected (:issue:`1518`). A
 protocol constructed from its own octets is not counted itself, so the count
 starts at the first layer it dissects. One chain of extension headers is also bounded on

pcapkit/foundation/extraction.py

@@ -800,7 +800,7 @@ def run(self) -> 'None':  # pylint: disable=inconsistent-return-statements
 
         Raises:
             FormatError: If the selected engine cannot read the input's format --
-                for the default engine, if it is neither PCAP nor PCAP-NG -- or if
+                for the :term:`default engine`, if it is neither PCAP nor PCAP-NG -- or if
                 the built-in PCAP-NG engine reads a PCAP-NG input to PCAP output.
 
         :rtype: None
@@ -837,7 +837,7 @@ def _select_engine(self) -> 'Optional[Type[EngineBase]]':
 
         An engine that is unknown, not installed, or rules itself out via
         :meth:`~pcapkit.foundation.engines.engine.EngineBase.unsupported_reason`
-        is replaced by the default one, and :attr:`self._exnam
+        is replaced by the :term:`default engine`, and :attr:`self._exnam
         <pcapkit.foundation.extraction.Extractor._exnam>` is updated to match.
         :meth:`__init__` calls this before choosing the output format, so that
         the choice reflects the engine that runs rather than the one requested.

pcapkit/foundation/reassembly/ip.py

@@ -117,7 +117,7 @@ def reassembly(self, info: 'Packet[_AT]') -> 'None':
         """Reassembly procedure.
 
         Arguments:
-            info: info dict of packets to be reassembled
+            info: :term:`info` record of packets to be reassembled
 
         Note:
             A completed datagram's buffer is freed, as in the

pcapkit/foundation/reassembly/reassembly.py

@@ -240,7 +240,7 @@ def reassembly(self, info: '_PT') -> 'None':
         """Reassembly procedure.
 
         Arguments:
-            info: info dict of packets to be reassembled
+            info: :term:`info` record of packets to be reassembled
 
         """
         # clear cache

pcapkit/protocols/misc/null.py

@@ -116,7 +116,7 @@ def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,  # pylint: d
         self._data = b''
         #: io.BytesIO: Source data stream.
         self._file = io.BytesIO()
-        #: pcapkit.protocols.data.misc.null.NoPayload: Info dict of current instance.
+        #: pcapkit.protocols.data.misc.null.NoPayload: Data model of current instance.
         self._info = Data_NoPayload()
 
         #: pcapkit.protocols.misc.null.NoPayload: Payload of current instance.

pcapkit/protocols/protocol.py

@@ -595,16 +595,16 @@ def alias(self) -> 'str':
         """Acronym of current protocol."""
         return self.__class__.__name__
 
-    # key name for the info dict
+    # key name for the data model
     @property
     def info_name(self) -> 'str':
-        """Key name of the :attr:`info` dict."""
+        """Key the enclosing layer's :term:`data model` holds :attr:`info` under."""
         return self.__class__.__name__.lower()
 
-    # info dict of current instance
+    # data model of current instance
     @property
     def info(self) -> '_PT':
-        """Info dict of current instance."""
+        """Parsed :term:`data model` of current instance."""
         return self._info
 
     # binary packet data if current instance
@@ -669,10 +669,10 @@ def packet(self) -> 'Data_Packet':
                 payload=self._read_packet(),
             )
 
-    # schema data
+    # header schema
     @cached_property
     def schema(self) -> '_ST':
-        """Schema data of the protocol."""
+        """Header :term:`schema` instance of the protocol."""
         return self.__header__
 
     # caller supplied parsing context
@@ -1361,7 +1361,7 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional
         # post-init customisations
         self.__post_init__(file, length, **kwargs)  # type: ignore[arg-type]
 
-        # inject packet payload to the info dict
+        # inject packet payload into the data model
         self._info.__update__(packet=self.packet.payload)
 
     @overload  # pragma: no cover
@@ -1415,7 +1415,7 @@ def __init_subclass__(cls, /, schema: 'Optional[Type[_ST]]' = None,
         This method is called when a subclass of :class:`Protocol` is defined.
         It is used to set the :attr:`self.__schema__ <pcapkit.protocols.protocol.Protocol.__schema__>`
         attribute of the subclass, and, if ``code`` is given, to register the
-        subclass into the next-layer dispatch registry (or registries) that
+        subclass into the next-layer dispatch :term:`registry` (or registries) that
         ``code`` names -- e.g. :attr:`Link.__proto__
         <pcapkit.protocols.link.link.Link.__proto__>`.
 
@@ -2233,7 +2233,7 @@ def _lookup_nested(data: 'Data') -> 'list[str]':
 
     @staticmethod
     def _lookup_registry(registry: 'DefaultDict[Any, _VT]', code: 'Any') -> '_VT':
-        """Look up a dispatch registry entry without recording a miss.
+        """Look up a dispatch :term:`registry` entry without recording a miss.
 
         Arguments:
             registry: dispatch registry to read, i.e. :attr:`self.__proto__