You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: add a glossary for terms with several meanings (registry, schema/data model/info, default engine) #1949
A few words in the docs carry several meanings, and no single page tells them apart, so a link to one explanation cannot resolve them:
registry: a pcapkit.const enumeration (pcapkit/const/index.rst:14), an upstream IANA registry (index.rst:117), the registration functions (foundation/registry.rst), and EnumMeta.registry (pcapkit/protocols/schema/schema.py:1259). contributing/conventions/test-coverage.rst:11 uses two of these senses close together.
schema / data model / info: defined only in the extension guide (ext.rst). Protocol.data is raw bytes, Protocol.info returns a data model but its docstring calls it an "Info dict" (protocol.py:607), and Protocol.schema is "Schema data".
default engine: used across the engine and extraction docs, never defined. engines/builtin.rst does not use the word.
Proposal: add docs/source/glossary.rst, a .. glossary:: holding only these terms. Each entry gets one or two sentences saying which sense applies, plus a link to the page that explains it, so it never becomes a second explanation. Put it in the "Guides & Changelog" toctree between demo and changelog. Point the ambiguous mentions at it with :term:, and fix the "Info dict" docstring.
Terms that have one canonical explanation keep linking to it (:ref:/:doc: or an rst_epilog substitution, as in #1948), not to the glossary. A test pins the entries and that every :term: resolves.
Blocked until #1946 and #1948 merge: both edit protocol.py and the engines pages this would touch.
Activity
docs: fix the glossary's info entry wording (#1949)
docs: add a glossary for terms with several meanings (#1949) (#1955)