docs: reconcile the Sphinx directives to the contract-versus-recipe tenet (#684)

CONTRIBUTING.md

@@ -89,6 +89,58 @@ GitHub's own rendering and the release body rather than Sphinx. The issue and pu
 under `.github/` are Markdown for the same reason. The exception ends there: anything added under
 `docs/source/` is `.rst`.
 
+### What belongs in the API reference: document the contract, hide the recipe
+
+The tenet is to **keep the usage and extensibility clear and straightforward, while hiding the
+recipe**. A member earns an autodoc directive because a reader needs it, not because of its spelling —
+so a leading underscore is not by itself a reason to leave something out, and being public is not by
+itself a reason to put it in.
+
+**Contract — document it.** Anything a *caller* needs in order to use a class, and anything an
+*implementer* needs in order to subclass it:
+
+- **Per-option and per-parameter `_read_*` / `_make_*` pairs.** These publish the data format: the
+  keyword arguments a caller passes to construct that option, and the fields they get back when
+  parsing it. There is nowhere else to look it up, so they stay documented even though the dispatch
+  reaches them through `getattr` rather than by name.
+- **Most class private attributes.** A private attribute that carries a subclass's state, or that a
+  subclass sets or reads, is contract. Keep it unless there is a specific reason it is not.
+- **Anything abstract, or implemented across subclasses.** An `@abstractmethod`, or an overridable
+  hook a subclass is expected to provide — `_make_data` has a concrete base implementation on
+  `ProtocolBase` and is overridden in 28 protocol modules, which is exactly the case this covers.
+- **Members whose observable behaviour is documented**, such as a method whose docstring records the
+  warning it emits or a guarantee it makes. A reader who hits that warning looks it up here.
+
+**Recipe — leave it out.** The implementation detail that is on nobody's usage or extensibility
+surface. In practice this is chiefly **module-level privates**: a private helper function, a lazily
+imported backend flag, an internal lock, a private wrapper class nobody constructs or subclasses.
+Removing one of these takes its members with it, which is correct — a member of a private class is
+reachable only through that class.
+
+The sweep runs **in both directions**. A must-implement member with no directive is the same defect as
+a recipe body with one, only quieter: add the missing directive rather than aiming for a small diff.
+
+Two mechanical points that decide real cases:
+
+- **A private base class must stay documented when a documented subclass carries
+  `:show-inheritance:`.** Sphinx renders that subclass's `Bases:` line as a link into the private
+  class's page, so dropping the directive breaks a link a public page really does render. This is what
+  keeps `pcapkit.protocols.schema.misc.pcapng._OPT_Option` and its five siblings, plus `_IPField`,
+  `_IPInterfaceField` and `_TextField`.
+- **Dunders keep their directives.** A `__dunder__` is reached through public syntax rather than by
+  name — `__len__` is what `len()` calls, `__getitem__` is what `obj[key]` does — so overriding one
+  changes behaviour a caller observes without ever writing the name. PyPCAPKit's own `__proto__`,
+  `__option__`, `__schema__` and `__protocol_name__` family is the documented extension contract that
+  subclass authors and the `register_*` functions write to: public API in everything but spelling.
+
+One shape to know about because it is invisible: every const enum carries a `_missing_` fallback that
+resolves an unregistered value and registers it, rather than raising as a plain `enum` would. That is
+deliberate and it is the extensibility behaviour of the whole `pcapkit.const` package, so it is
+documented once on the package's landing page rather than restated on each of the 121 enumerations
+under `pcapkit/const/` that implement it. Note `docs/source/conf.py` already names `_missing_` in
+`autodoc_default_options['exclude-members']`, so a per-class directive would be arguing with the
+project's own configuration.
+
 ## Coding style
 
 [PEP 8](https://peps.python.org/pep-0008/) is the baseline, but the repository's own linters are the

docs/source/pcapkit/const/index.rst

@@ -6,6 +6,36 @@ Constant Enumerations
 This module contains all constant enumerations of :mod:`pcapkit`, which are
 automatically generated from the :mod:`pcapkit.vendor` module.
 
+.. _unrecognised-values:
+
+Unrecognised Values
+-------------------
+
+Every enumeration 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
+the registry does not define does **not** raise. Each class overrides
+``_missing_`` so that a value inside the registry's valid range is minted into a
+new member on the fly -- via ``aenum.extend_enum``, named for the unassigned or
+reserved band it falls in -- and returned. Only a value outside that range, or of
+the wrong type, raises :exc:`ValueError`.
+
+That is what makes the enumerations usable against live capture data, where a
+protocol number assigned after this release was generated is a routine
+occurrence rather than an error. It also means an enumeration member is not a
+closed set: the identity of a minted member is stable for the life of the
+process, but it does not exist until something asks for it.
+
+The mechanism is uniform because it is generated -- see
+:mod:`pcapkit.vendor.default`, whose template emits the ``_missing_`` override
+for every registry -- while the valid range and the names of the unassigned bands
+are per-registry, taken from that registry's own IANA data. The individual
+overrides are therefore not documented per class.
+
+.. seealso::
+
+   :doc:`../foundation/registry` covers the other half of extending a registry:
+   once a code exists, registering a parser class, schema or engine against it.
+
 Protocol Numbers
 ----------------
 

docs/source/pcapkit/corekit/fields/field.rst

@@ -7,10 +7,18 @@ Base Fields
    :members:
    :show-inheritance:
 
+   .. autoattribute:: _length
+   .. autoattribute:: _length_callback
+
 .. autoclass:: pcapkit.corekit.fields.field.FieldBase
    :members:
    :show-inheritance:
 
+   .. autoattribute:: _name
+   .. autoattribute:: _template
+   .. autoattribute:: _default
+   .. autoattribute:: _callback
+
 Auxiliaries
 -----------
 

docs/source/pcapkit/corekit/io.rst

@@ -14,6 +14,9 @@ implementation to :class:`io.BufferedReader`.
    .. autoproperty:: raw
    .. autoproperty:: closed
 
+   .. autoattribute:: _stream
+   .. autoattribute:: _closed
+
    .. automethod:: read
    .. automethod:: read1
    .. automethod:: readinto

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

@@ -216,6 +216,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
 
    .. autoattribute:: _expkg
    .. autoattribute:: _extmp
+   .. autoattribute:: _backend
    .. autoattribute:: _dlink
    .. autoattribute:: _closed
 
@@ -369,6 +370,7 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    .. autoattribute:: _expkg
    .. autoattribute:: _handle
    .. autoattribute:: _extmp
+   .. autoattribute:: _backend
    .. autoattribute:: _dlink
    .. autoattribute:: _closed
 
@@ -415,13 +417,6 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
 Internal Definitions
 --------------------
 
-.. autoclass:: pcapkit.foundation.engines.pypcapfile._NamedStream
-   :no-members:
-   :show-inheritance:
-
-   .. autoattribute:: name
-   .. automethod:: read
-
 .. automethod:: pcapkit.foundation.engines.pypcapfile.PyPCAPFile._get_decoder
 .. automethod:: pcapkit.foundation.engines.pypcapfile.PyPCAPFile._decode
 

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

@@ -25,6 +25,11 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    .. automethod:: run
    .. automethod:: read_frame
 
+   .. autoattribute:: _gbhdr
+   .. autoattribute:: _vinfo
+   .. autoattribute:: _dlink
+   .. autoattribute:: _nnsec
+
 PCAP-NG Support
 ===============
 
@@ -43,6 +48,9 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
    .. automethod:: run
    .. automethod:: read_frame
 
+   .. autoattribute:: _ctx
+   .. autoattribute:: _ctx_list
+
 Internal Definitions
 --------------------
 

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

@@ -51,6 +51,8 @@ all engine support functionality.
 
    .. autoproperty:: extractor
 
+   .. autoattribute:: _extractor
+
    .. automethod:: unsupported_reason
 
    .. automethod:: run

docs/source/pcapkit/foundation/extraction.rst

@@ -61,6 +61,7 @@ extracts parametres from a PCAP file.
    .. autoattribute:: _flag_a
    .. autoattribute:: _flag_d
    .. autoattribute:: _flag_e
+   .. autoattribute:: _flag_f
    .. autoattribute:: _flag_q
    .. autoattribute:: _flag_r
    .. autoattribute:: _flag_t
@@ -70,10 +71,22 @@ extracts parametres from a PCAP file.
 
    .. autoattribute:: _ifile
    .. autoattribute:: _ofile
+   .. autoattribute:: _ifnm
+   .. autoattribute:: _ofnm
+   .. autoattribute:: _fext
+   .. autoattribute:: _offmt
+   .. autoattribute:: _magic
 
    .. autoattribute:: _frnum
+   .. autoattribute:: _frame
    .. autoattribute:: _reasm
    .. autoattribute:: _trace
+   .. autoattribute:: _ipv4
+   .. autoattribute:: _ipv6
+   .. autoattribute:: _tcp
+
+   .. autoattribute:: _eof_mark
+   .. autoattribute:: _vfunc
 
    .. autoattribute:: _exnam
    .. autoattribute:: _exeng

docs/source/pcapkit/foundation/registry.rst

@@ -7,6 +7,12 @@ This module (:mod:`pcapkit.foundation.registry`) provides the registry
 management for :mod:`pcapkit`, as the module contains various registry
 points.
 
+Every registration below takes a code that is already an enumeration member. For
+how a code the shipped registries do not define becomes one in the first place,
+see :ref:`unrecognised-values` -- the constant enumerations mint an in-range
+unknown value rather than rejecting it, which is what makes registering against a
+newly assigned number possible without regenerating them.
+
 Foundation Registries
 ---------------------
 

docs/source/pcapkit/foundation/traceflow/traceflow.rst

@@ -73,6 +73,19 @@ which is an abstract base class for all flow tracing classes.
    .. autoattribute:: _bidir
       :no-value:
 
+   .. autoattribute:: _fproot
+      :no-value:
+   .. autoattribute:: _foutio
+      :no-value:
+   .. autoattribute:: _fdpext
+      :no-value:
+   .. autoattribute:: _endian
+      :no-value:
+   .. autoattribute:: _nnsecd
+      :no-value:
+   .. autoattribute:: _analyse
+      :no-value:
+
    .. automethod:: __call__
    .. automethod:: __init_subclass__
 

docs/source/pcapkit/protocols/application/ngap.rst

@@ -106,15 +106,6 @@ Auxiliary Functions
 
 .. autofunction:: pcapkit.protocols.application.ngap.load_pycrate
 
-.. autodata:: pcapkit.protocols.application.ngap._PYCRATE
-
-.. autodata:: pcapkit.protocols.application.ngap._PDU_LOCK
-   :no-value:
-
-.. autofunction:: pcapkit.protocols.application.ngap._convert
-
-.. autofunction:: pcapkit.protocols.application.ngap._revert
-
 Auxiliary Data
 --------------
 

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

@@ -223,8 +223,6 @@ MD5, DES-MAC, KPDK-MD5       MUST NOT            **no**       registered, delibe
 
 .. autodata:: pcapkit.protocols.internet.esp.INTEGRITY_SUITES
 
-.. autofunction:: pcapkit.protocols.internet.esp._resolve
-
 Known Limitations
 -----------------
 
@@ -251,8 +249,6 @@ Processing Status
 
 .. autofunction:: pcapkit.protocols.internet.esp.load_cryptography
 
-.. autodata:: pcapkit.protocols.internet.esp._CRYPTO
-
 Header Schemas
 --------------
 

docs/source/pcapkit/protocols/protocol.rst

@@ -70,6 +70,10 @@ utility arguments and methods of specified protocols.
    .. autoattribute:: _data
    .. autoattribute:: _file
    .. autoattribute:: _info
+   .. autoattribute:: _next
+   .. autoattribute:: _protos
+   .. autoattribute:: _seekset
+   .. autoattribute:: _sigterm
    .. autoattribute:: __data__
 
    .. automethod:: __init__