docs(corekit,const,vendor): seventh whole-repo pass over corekit, const and vendor (#1103) (#2264)

Full read of pcapkit/corekit, the vendor crawlers and templates, the
hand-written const prose and their API pages.

- corekit: FieldBase.unpack example, _nested_types target, EnumRegistry
  covers open enums only, parse_ip_address claim narrowed, NoDefaultType
  and parse_ip_address change-relative wording.
- vendor: Method.get and _sanitize_identifier template text (mirrored into
  the generated const modules), TLSKeyLabel, AppType Record/svc, mh flag
  process Returns, L2TP process, ipx RFC sections by name, PCAP-NG Hash
  Algorithms anchor, ExtensionHeader/EtherType comments.
- const: index page raise bands and source data, PCAP-NG anchor, VLAN
  class role, OSPF title underline.

Author: JarryShaw

docs/source/pcapkit/const/index.rst

@@ -14,9 +14,9 @@ Unrecognised Values
 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
-unassigned or reserved band it falls in. Only a value outside that range, or of the
-wrong type, raises :exc:`ValueError`.
+member-like object for a value that falls in one of the registry's unassigned or
+reserved bands, named for that band. Only a value no band covers, or of the wrong
+type, raises :exc:`ValueError`.
 
 In almost every registry that object is **not** installed: the registry does not
 grow, and a second lookup of the same value returns an equal but distinct object.
@@ -38,15 +38,15 @@ Some behave otherwise, and :ref:`mint-criterion` gives the full split:
 
 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
+occurrence rather than an error. It also means an enumeration is not a
 closed set: an unassigned value resolves to a member that is, apart from
 :class:`~pcapkit.const.mh.cga_type.CGAType`, absent from iteration and ``__members__``,
 and whether a repeat lookup returns the same object varies by registry, so compare such
 members by value, not identity.
 
 The common form of the override is generated -- see :mod:`pcapkit.vendor.default`,
 whose template emits it -- while the valid range and the names of the unassigned
-bands are per-registry, taken from that registry's own IANA data. The individual
+bands are per-registry, taken from that registry's own source data. The individual
 overrides are therefore not documented per class.
 
 .. seealso::

docs/source/pcapkit/const/pcapng.rst

@@ -150,7 +150,7 @@ which is automatically generated from :class:`pcapkit.vendor.pcapng.tls_key_labe
 
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-standardized-block-type-cod
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-options
-.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-flags
+.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-optio
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-name-resolution-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-decryption-secrets-block

docs/source/pcapkit/const/vlan.rst

@@ -10,7 +10,7 @@ enumerations include:
 
 .. list-table::
 
-   * - :const:`VLAN_PriorityLevel <pcapkit.const.vlan.priority_level.PriorityLevel>`
+   * - :class:`VLAN_PriorityLevel <pcapkit.const.vlan.priority_level.PriorityLevel>`
      - Priority Levels [*]_
 
 Priority levels defined in IEEE 802.1p

docs/source/pcapkit/vendor/pcapng.rst

@@ -139,7 +139,7 @@ which is automatically generating :class:`pcapkit.const.pcapng.tls_key_label.TLS
 
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-standardized-block-type-cod
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-options
-.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-flags
+.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-optio
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-name-resolution-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-decryption-secrets-block

pcapkit/const/ftp/command.py

@@ -37,8 +37,8 @@ class FEATCode(EnumRegistry, StrEnum):
        :meth:`~pcapkit.vendor.ftp.command.Command.process`) -- rather than
        minting the per-command ones at import time as an incidental side
        effect of building :class:`Command`'s own rows. GitHub issue :issue:`860`:
-       that import-time mutation was the same defect shape :issue:`775` removed
-       from :class:`~pcapkit.const.pcapng.filter_type.FilterType`. ``_missing_``
+       that import-time mutation is the same defect shape :issue:`775` rules
+       out on :class:`~pcapkit.const.pcapng.filter_type.FilterType`. ``_missing_``
        still unmints for a keyword that
        turns up on the wire but names none of these -- the extendability the
        owner conditionally asked to keep on GitHub issue :issue:`860`: unsure what a

pcapkit/const/http/method.py

@@ -226,8 +226,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
         IANA methods whose member *name* differs from their *value* --
         ``BASELINE_CONTROL`` / ``'BASELINE-CONTROL'`` and
         ``VERSION_CONTROL`` / ``'VERSION-CONTROL'``, a hyphen being unusable
-        in a Python identifier -- which :meth:`_missing_` (and so the
-        constructor) also finds by value.
+        in a Python identifier -- which the constructor also finds by
+        value, before it falls back to :meth:`_missing_`.
 
         It is a :class:`classmethod`, as the base is, because a
         zero-argument ``super()`` needs a first argument to bind

pcapkit/const/ospf/__init__.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=unused-import
 """:class:`~pcapkit.protocols.application.ospf.OSPF` Constant Enumerations
-======================================================================
+=======================================================================
 
 .. module:: pcapkit.const.ospf
 

pcapkit/const/pcapng/__init__.py

@@ -30,7 +30,7 @@
 
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-standardized-block-type-cod
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-options
-.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-flags
+.. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block-optio
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-enhanced-packet-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-name-resolution-block
 .. [*] https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-03.html#name-decryption-secrets-block

pcapkit/const/reg/apptype/__init__.py

@@ -59,7 +59,7 @@
 
 #: Registries imported on first use rather than with this package, as submodule
 #: name to class name -- GitHub issue :issue:`1538`. Generated from IANA's
-#: registry, the two hold about 49,700 lines of members, about 30% of
+#: registry, they hold about 49,700 lines of members, about 30% of
 #: ``import pcapkit`` when imported eagerly, while SCTP's and DCCP's cost a few
 #: milliseconds and stay eager.
 _LAZY = {'tcp': 'TCP', 'udp': 'UDP'}

pcapkit/const/reg/apptype/apptype.py

@@ -2734,7 +2734,8 @@ def _sanitize_identifier(cls, name: 'str') -> 'str':
         collapsed = '_'.join(stripped.split())
         replaced = re.sub(r'\W', '_', collapsed)
         identifier = '_'.join(filter(None, replaced.split('_')))
-        # NOTE: matches process()'s own keyword guard below -- a name that
+        # NOTE: matches the keyword guard AppType.process applies at generation
+        # time in pcapkit.vendor.reg.apptype.apptype -- a name that
         # sanitises to a reserved word is not usable as an attribute as is,
         # and a trailing underscore is the same fix the generator already
         # applies to a statically declared member with the same problem.