docs: state current behaviour where text pins held change-relative wording (#2228)

docs/source/contributing/conventions/sentinel-convention.rst

@@ -105,9 +105,10 @@ appears in a signature, in :func:`help` output and in a traceback. Compare what
 as written: the value of a vendored copy is that it can still be diffed against
 upstream, and a house-style rewrite destroys that in exchange for a sentinel nobody
 outside the port ever sees. The rule above is for sentinels this package writes
-itself. The case that settled it, ``_NOT_FOUND = object()`` in the
-:class:`~pcapkit.utilities.compat.cached_property` backport for interpreters below
-3.8, went with that backport when 1.5.0 raised the floor to 3.8 (:issue:`2051`).
+itself. The ruling was made for ``_NOT_FOUND = object()`` in the backport of
+:func:`functools.cached_property` that served interpreters below 3.8. With the floor
+at 3.8, :class:`~pcapkit.utilities.compat.cached_property` is a re-export of
+:func:`functools.cached_property` itself (:issue:`2051`).
 
 Per-Sentinel Dunder Methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

pcapkit/const/http/method.py

@@ -267,9 +267,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
                 reach ``_missing_``, and is **not** caught by
                 the miss fallback described under *Returns* -- only a failed
                 lookup is. Raising is the intended behaviour for
-                ``get(b'GET')`` as well: a member whose name and
-                value were both the :class:`bytes` object is not a thing
-                this registry should hand back.
+                ``get(b'GET')`` as well, since no member of this registry
+                has a :class:`bytes` name or value.
 
         """
         try:

pcapkit/const/reg/apptype/apptype.py

@@ -2513,10 +2513,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
             key: Port number the caller is looking up, validated here so that
                 every entry point rejects a non-port identically.
             proto: Transport protocol, as a member, its name, or a bare
-                :class:`int`. That last shape is not merely defensive: GitHub
-                issue :issue:`808` dropped
-                :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`'s
-                ``IntFlag`` base, so
+                :class:`int`. That last shape is not merely defensive:
+                :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`
+                is an ``IntEnum``, not an ``IntFlag`` (GitHub issue
+                :issue:`808`), so
                 ``TransportProtocol.a | TransportProtocol.b`` -- built by hand,
                 the same as any caller passing a literal port-transport bitmask
                 -- falls through to ``int.__or__`` and returns a bare

pcapkit/vendor/http/method.py

@@ -172,9 +172,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}':
                 reach ``_missing_``, and is **not** caught by
                 the miss fallback described under *Returns* -- only a failed
                 lookup is. Raising is the intended behaviour for
-                ``get(b'GET')`` as well: a member whose name and
-                value were both the :class:`bytes` object is not a thing
-                this registry should hand back.
+                ``get(b'GET')`` as well, since no member of this registry
+                has a :class:`bytes` name or value.
 
         """
         try:

pcapkit/vendor/reg/apptype/apptype.py

@@ -467,10 +467,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
             key: Port number the caller is looking up, validated here so that
                 every entry point rejects a non-port identically.
             proto: Transport protocol, as a member, its name, or a bare
-                :class:`int`. That last shape is not merely defensive: GitHub
-                issue :issue:`808` dropped
-                :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`'s
-                ``IntFlag`` base, so
+                :class:`int`. That last shape is not merely defensive:
+                :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`
+                is an ``IntEnum``, not an ``IntFlag`` (GitHub issue
+                :issue:`808`), so
                 ``TransportProtocol.a | TransportProtocol.b`` -- built by hand,
                 the same as any caller passing a literal port-transport bitmask
                 -- falls through to ``int.__or__`` and returns a bare

tests/const/test_const_method_value_lookup_908_unit.py

@@ -302,8 +302,8 @@ def test_the_docstring_documents_the_value_error(self) -> None:
         # NOTE: a distinctive sentence rather than the bare word
         # ``ValueError``, which occurs incidentally elsewhere in 4kB of
         # docstring and would make this assertion near-vacuous.
-        self.assertIn('value were both the :class:`bytes` object', source)
-        self.assertIn('value were both the :class:`bytes` object', rendered)
+        self.assertIn('has a :class:`bytes` name or value', source)
+        self.assertIn('has a :class:`bytes` name or value', rendered)
 
 
 class VendorTemplateParityTests(unittest.TestCase):

tests/project/test_changelog_md.py

@@ -419,9 +419,9 @@ def test_markdown_metacharacters_are_escaped_in_text_and_target(self) -> None:
         self.assertIn(r'[a \[b\]](https://en.wikipedia.org/wiki/Foo_%28bar%29%20baz)', markdown)
 
     def test_an_unknown_role_is_still_fatal(self) -> None:
-        # Shows the guard was not loosened; it is not evidence of new behaviour. The
-        # ``:ref:`` half passed before the change too -- only the ``:issue:`` half
-        # failed without it, by being left unconverted.
+        # The guard refuses a role it does not know: the ``:ref:`` half is left
+        # unconverted and raises, and the ``:issue:`` half converts, so only
+        # ``:ref:`` is named in the error.
         index = self.make_tree(
             entry=ENTRY + '\nSee :issue:`29` and :ref:`changelog` for more.\n')
 

tests/project/test_docs_internal_refs_1940_unit.py

@@ -101,7 +101,7 @@
      ':class:`~pcapkit.const.ftp.command.CommandType`'),
     ('docs/source/contributing/conventions/sentinel-convention.rst', '``NoDefaultType``',
      ':class:`~pcapkit.corekit.sentinels.NoDefaultType`'),
-    # On this page with the backport it names (#2051).
+    # On this page as the re-export of functools.cached_property (#2051).
     ('docs/source/contributing/conventions/sentinel-convention.rst', '``cached_property``',
      ':class:`~pcapkit.utilities.compat.cached_property`'),
     ('docs/source/contributing/releasing.rst', '``pcapkit.__version__``',

tests/project/test_docs_internal_refs_1947_unit.py

@@ -37,10 +37,10 @@
 
 #: ``(source, literal in context, the same context with the role)``.
 CONVERTED = (
-    ('pcapkit/vendor/reg/apptype/apptype.py', "dropped ``TransportProtocol``'s",
-     f"dropped\n                {TRANSPORT_PROTOCOL}'s"),
-    ('pcapkit/const/reg/apptype/apptype.py', "dropped ``TransportProtocol``'s",
-     f"dropped\n                {TRANSPORT_PROTOCOL}'s"),
+    ('pcapkit/vendor/reg/apptype/apptype.py', '``TransportProtocol`` is an ``IntEnum``',
+     f'{TRANSPORT_PROTOCOL}\n                is an ``IntEnum``'),
+    ('pcapkit/const/reg/apptype/apptype.py', '``TransportProtocol`` is an ``IntEnum``',
+     f'{TRANSPORT_PROTOCOL}\n                is an ``IntEnum``'),
     ('pcapkit/vendor/reg/apptype/apptype.py', 'as a ``TransportProtocol`` expression',
      f'as a\n        {TRANSPORT_PROTOCOL} expression'),
 ) + tuple(

tests/project/test_issue_refs_in_comments.py

@@ -42,7 +42,7 @@
      '# ``:issue:`` would link to a page that does not exist.'),
     # Describes the changelog converter's test input, which uses the role.
     ('tests/project/test_changelog_md.py',
-     '# ``:ref:`` half passed before the change too -- only the ``:issue:`` half'),
+     '# unconverted and raises, and the ``:issue:`` half converts, so only'),
 })