Skip to content

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

Merged
JarryShaw merged 2 commits into
mainfrom
docs/1949-glossary
Oct 19, 2026
Merged

JarryShaw merged 2 commits into
mainfrom
docs/1949-glossary

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

What is the purpose of your pull request?

  • docs — documentation only

Description of your pull request and other information

Adds docs/source/glossary.rst for the words with several meanings: registry, schema, data model, info and default engine (#1949). Each entry names its senses and links to the page that explains them, so it never repeats an explanation. The page sits between demo and changelog.

  • Ambiguous mentions on the engine, extraction, constants, test-coverage and protocol pages and docstrings link to it with :term:.
  • Protocol.info now says it returns a data model rather than an "Info dict". The wording of info_name, schema and NoPayload._info is changed to match.
  • ext.rst gains an ext-new-protocol label for the glossary to link to.

tests/project/test_docs_glossary_1949_unit.py pins the page, its entries and links, and that every :term: role resolves, since CI's make html only warns on an unknown term. It fails on main. The docs build has no warnings.

Closes #1949

- add docs/source/glossary.rst for registry, schema, data model, info and
  default engine; each entry names its senses and links to the page that
  explains them, and the page sits between demo and changelog
- point the ambiguous mentions in the engine, extraction, constants,
  test-coverage and protocol pages and docstrings at it with :term:
- say Protocol.info returns a data model rather than an "Info dict", and
  fix the matching info_name, schema and NoPayload wording
- label the extension guide's New Protocol section so the glossary links it
- add tests/project/test_docs_glossary_1949_unit.py, which pins the page, its
  entries and links, and that every :term: role names a defined term

Closes #1949
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

NEEDS CHANGES at b6350a74d, one sentence. A Sonnet review checked each entry's senses against the code: Protocol.info/info_name, the default-engine fallback and magic-number choice, EnumMeta.registry, and reasm.tcp.packet. All of them hold. The docs build has 0 warnings, with no duplicate-term clash against the existing glossaries. Every :term: resolves, and the new test fails on main. The one fix is the info entry's "which the enclosing layer's holds under". It is missing its noun and is being reworded in a follow-up commit.

@JarryShaw JarryShaw added review: needs-changes Cross-review at the current head says changes are required; see the verdict comment and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
- supply the missing noun in the info entry: the data model is stored in
  the enclosing layer's data model under info_name
- say what the extension guide explains in the data model entry, rather
  than an unclear "it"
@JarryShaw JarryShaw added review: running A cross-review is in flight against the current head - no verdict yet and removed review: needs-changes Cross-review at the current head says changes are required; see the verdict comment labels Oct 19, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

GOOD TO GO at f3a65c536. A Sonnet delta review confirmed the new commit touches only glossary.rst. The info entry now reads correctly and matches Protocol.info_name in protocol.py, and all five entries read cleanly. The glossary test passes.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: running A cross-review is in flight against the current head - no verdict yet labels Oct 19, 2026
@JarryShaw
JarryShaw merged commit c8c34a8 into main Oct 19, 2026
8 checks passed
@JarryShaw
JarryShaw deleted the docs/1949-glossary branch October 19, 2026 19:24
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Oct 19, 2026
@JarryShaw JarryShaw moved this to Done in PyPCAPKit Oct 19, 2026
@JarryShaw JarryShaw added this to the PyPCAPKit v1.5 milestone Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

docs: add a glossary for terms with several meanings (registry, schema/data model/info, default engine)

1 participant