review comments/clarifications

Author: ksunden

doc/devel/contribute.rst

@@ -345,7 +345,7 @@ Introducing
    - Use ``_api.warn_deprecated()`` for general deprecation warnings
    - Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
      methods, or properties
-   - Use the decorator ``@_api.deprecate_privatize_attribute`` to deprecate
+   - Use ``@_api.deprecate_privatize_attribute`` to annotate deprecation of
      attributes while keeping the internal private version.
    - To warn on changes of the function signature, use the decorators
      ``@_api.delete_parameter``, ``@_api.rename_parameter``, and
@@ -370,7 +370,7 @@ Introducing
     ``param: <type> = ...``). Even so, the decorator changes the default value to a
     sentinel value which should not be included in the type stub. Thus, Mypy Stubtest
     needs to be informed of the inconsistency by placing the method into
-    ``ci/mypy-stubtest-allowlist.txt`` under a heading indicating the deprecation
+    :file:`ci/mypy-stubtest-allowlist.txt` under a heading indicating the deprecation
     version number.
 
 Expiring
@@ -389,11 +389,11 @@ Expiring
   - Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
     are to be removed on expiry.
   - Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
-    will have been updated at introduction.
+    will have been updated at introduction, and require no change now.
   - Items decorated with ``@_api.delete_parameter`` will need to be updated to the
     final signature, in the same way as the ``.py`` file signature is updated.
-    The entry in ``ci/mypy-stubtest-allowlist.txt`` should be removed.
-  - Any other entries in ``ci/mypy-stubtest-allowlist.txt`` under a versions
+    The entry in :file:`ci/mypy-stubtest-allowlist.txt` should be removed.
+  - Any other entries in :file:`ci/mypy-stubtest-allowlist.txt` under a version's
     deprecations should be double checked, as only ``delete_parameter`` should normally
     require that mechanism for deprecation. For removed items that were not in the stub
     file, only deleting from the allowlist is required.