Docs: align usage of versionadded/versionchanged with recommended practice (#114409)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: Ezio Melotti <[email protected]>

Author: 3 people

Doc/library/argparse.rst

@@ -1936,8 +1936,8 @@ FileType objects
       >>> parser.parse_args(['-'])
       Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
 
-   .. versionadded:: 3.4
-      The *encodings* and *errors* keyword arguments.
+   .. versionchanged:: 3.4
+      Added the *encodings* and *errors* parameters.
 
 
 Argument groups

Doc/library/asyncio-stream.rst

@@ -77,8 +77,8 @@ and work with streams:
    .. versionchanged:: 3.7
       Added the *ssl_handshake_timeout* parameter.
 
-   .. versionadded:: 3.8
-      Added *happy_eyeballs_delay* and *interleave* parameters.
+   .. versionchanged:: 3.8
+      Added the *happy_eyeballs_delay* and *interleave* parameters.
 
    .. versionchanged:: 3.10
       Removed the *loop* parameter.

Doc/library/bdb.rst

@@ -132,8 +132,8 @@ The :mod:`bdb` module also defines two classes:
    frame is considered to originate in a certain module is determined
    by the ``__name__`` in the frame globals.
 
-   .. versionadded:: 3.1
-      The *skip* argument.
+   .. versionchanged:: 3.1
+      Added the *skip* parameter.
 
    The following methods of :class:`Bdb` normally don't need to be overridden.
 

Doc/library/concurrent.futures.rst

@@ -171,8 +171,8 @@ And::
       should be higher than the number of workers
       for :class:`ProcessPoolExecutor`.
 
-   .. versionadded:: 3.6
-      The *thread_name_prefix* argument was added to allow users to
+   .. versionchanged:: 3.6
+      Added the *thread_name_prefix* parameter to allow users to
       control the :class:`threading.Thread` names for worker threads created by
       the pool for easier debugging.
 

Doc/library/configparser.rst

@@ -1045,14 +1045,14 @@ ConfigParser Objects
          config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
                      encoding='cp1250')
 
-      .. versionadded:: 3.2
-         The *encoding* parameter.  Previously, all files were read using the
-         default encoding for :func:`open`.
+      .. versionchanged:: 3.2
+         Added the *encoding* parameter.
+         Previously, all files were read using the default encoding for :func:`open`.
 
-      .. versionadded:: 3.6.1
+      .. versionchanged:: 3.6.1
          The *filenames* parameter accepts a :term:`path-like object`.
 
-      .. versionadded:: 3.7
+      .. versionchanged:: 3.7
          The *filenames* parameter accepts a :class:`bytes` object.
 
 
@@ -1291,9 +1291,9 @@ Exceptions
    that is already present or in strict parsers when a section if found more
    than once in a single input file, string or dictionary.
 
-   .. versionadded:: 3.2
-      Optional ``source`` and ``lineno`` attributes and arguments to
-      :meth:`!__init__` were added.
+   .. versionchanged:: 3.2
+      Added the optional *source* and *lineno* attributes and parameters to
+      :meth:`!__init__`.
 
 
 .. exception:: DuplicateOptionError

Doc/library/datetime.rst

@@ -859,8 +859,8 @@ Constructor:
 
    If an argument outside those ranges is given, :exc:`ValueError` is raised.
 
-   .. versionadded:: 3.6
-      Added the ``fold`` argument.
+   .. versionchanged:: 3.6
+      Added the *fold* parameter.
 
 Other constructors, all class methods:
 
@@ -1258,8 +1258,8 @@ Instance methods:
    :class:`datetime` objects are also supported by generic function
    :func:`copy.replace`.
 
-   .. versionadded:: 3.6
-      Added the ``fold`` argument.
+   .. versionchanged:: 3.6
+      Added the *fold* parameter.
 
 
 .. method:: datetime.astimezone(tz=None)
@@ -1502,8 +1502,8 @@ Instance methods:
       >>> dt.isoformat(timespec='microseconds')
       '2015-01-01T12:30:59.000000'
 
-   .. versionadded:: 3.6
-      Added the *timespec* argument.
+   .. versionchanged:: 3.6
+      Added the *timespec* parameter.
 
 
 .. method:: datetime.__str__()
@@ -1839,8 +1839,8 @@ Instance methods:
    :class:`time` objects are also supported by generic function
    :func:`copy.replace`.
 
-   .. versionadded:: 3.6
-      Added the ``fold`` argument.
+   .. versionchanged:: 3.6
+      Added the *fold* parameter.
 
 
 .. method:: time.isoformat(timespec='auto')
@@ -1883,8 +1883,8 @@ Instance methods:
       >>> dt.isoformat(timespec='auto')
       '12:34:56'
 
-   .. versionadded:: 3.6
-      Added the *timespec* argument.
+   .. versionchanged:: 3.6
+      Added the *timespec* parameter.
 
 
 .. method:: time.__str__()

Doc/library/difflib.rst

@@ -52,8 +52,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
    the purpose of sequence matching. This heuristic can be turned off by setting
    the ``autojunk`` argument to ``False`` when creating the :class:`SequenceMatcher`.
 
-   .. versionadded:: 3.2
-      The *autojunk* parameter.
+   .. versionchanged:: 3.2
+      Added the *autojunk* parameter.
 
 
 .. class:: Differ
@@ -383,8 +383,8 @@ The :class:`SequenceMatcher` class has this constructor:
    The optional argument *autojunk* can be used to disable the automatic junk
    heuristic.
 
-   .. versionadded:: 3.2
-      The *autojunk* parameter.
+   .. versionchanged:: 3.2
+      Added the *autojunk* parameter.
 
    SequenceMatcher objects get three data attributes: *bjunk* is the
    set of elements of *b* for which *isjunk* is ``True``; *bpopular* is the set of

Doc/library/email.policy.rst

@@ -219,7 +219,6 @@ added matters.  To illustrate::
       Default: :const:`False`.
 
       .. versionadded:: 3.5
-         The *mangle_from_* parameter.
 
 
    .. attribute:: message_factory

Doc/library/functions.rst

@@ -1073,8 +1073,8 @@ are always available.  They are listed here in alphabetical order.
    such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
    ``heapq.nlargest(1, iterable, key=keyfunc)``.
 
-   .. versionadded:: 3.4
-      The *default* keyword-only argument.
+   .. versionchanged:: 3.4
+      Added the *default* keyword-only parameter.
 
    .. versionchanged:: 3.8
       The *key* can be ``None``.
@@ -1111,8 +1111,8 @@ are always available.  They are listed here in alphabetical order.
    such as ``sorted(iterable, key=keyfunc)[0]`` and ``heapq.nsmallest(1,
    iterable, key=keyfunc)``.
 
-   .. versionadded:: 3.4
-      The *default* keyword-only argument.
+   .. versionchanged:: 3.4
+      Added the *default* keyword-only parameter.
 
    .. versionchanged:: 3.8
       The *key* can be ``None``.

Doc/library/functools.rst

@@ -194,7 +194,7 @@ The :mod:`functools` module defines the following functions:
    In contrast, the tuple arguments ``('answer', Decimal(42))`` and
    ``('answer', Fraction(42))`` are treated as equivalent.
 
-   The wrapped function is instrumented with a :func:`cache_parameters`
+   The wrapped function is instrumented with a :func:`!cache_parameters`
    function that returns a new :class:`dict` showing the values for *maxsize*
    and *typed*.  This is for information purposes only.  Mutating the values
    has no effect.
@@ -275,8 +275,8 @@ The :mod:`functools` module defines the following functions:
    .. versionchanged:: 3.8
       Added the *user_function* option.
 
-   .. versionadded:: 3.9
-      Added the function :func:`cache_parameters`
+   .. versionchanged:: 3.9
+      Added the function :func:`!cache_parameters`
 
 .. decorator:: total_ordering
 

Doc/library/http.client.rst

@@ -311,7 +311,7 @@ HTTPConnection Objects
       :class:`str` or bytes-like object that is not also a file as the
       body representation.
 
-   .. versionadded:: 3.2
+   .. versionchanged:: 3.2
       *body* can now be an iterable.
 
    .. versionchanged:: 3.6
@@ -461,9 +461,8 @@ also send your request step by step, by using the four functions below.
       This is to avoid premature termination of the read of the request by
       the target server due to malformed encoding.
 
-   .. versionadded:: 3.6
-      Chunked encoding support.  The *encode_chunked* parameter was
-      added.
+   .. versionchanged:: 3.6
+      Added chunked encoding support and the *encode_chunked* parameter.
 
 
 .. method:: HTTPConnection.send(data)

Doc/library/http.server.rst

@@ -328,8 +328,8 @@ provides three different variants:
    or the current directory if *directory* is not provided, directly
    mapping the directory structure to HTTP requests.
 
-   .. versionadded:: 3.7
-      The *directory* parameter.
+   .. versionchanged:: 3.7
+      Added the *directory* parameter.
 
    .. versionchanged:: 3.9
       The *directory* parameter accepts a :term:`path-like object`.
@@ -438,29 +438,29 @@ to bind to localhost only::
 
         python -m http.server --bind 127.0.0.1
 
-.. versionadded:: 3.4
-    ``--bind`` argument was introduced.
+.. versionchanged:: 3.4
+   Added the ``--bind`` option.
 
-.. versionadded:: 3.8
-    ``--bind`` argument enhanced to support IPv6
+.. versionchanged:: 3.8
+   Support IPv6 in the ``--bind`` option.
 
 By default, the server uses the current directory. The option ``-d/--directory``
 specifies a directory to which it should serve the files. For example,
 the following command uses a specific directory::
 
         python -m http.server --directory /tmp/
 
-.. versionadded:: 3.7
-    ``--directory`` argument was introduced.
+.. versionchanged:: 3.7
+   Added the ``--directory`` option.
 
 By default, the server is conformant to HTTP/1.0. The option ``-p/--protocol``
 specifies the HTTP version to which the server is conformant. For example, the
 following command runs an HTTP/1.1 conformant server::
 
         python -m http.server --protocol HTTP/1.1
 
-.. versionadded:: 3.11
-    ``--protocol`` argument was introduced.
+.. versionchanged:: 3.11
+   Added the ``--protocol`` option.
 
 .. class:: CGIHTTPRequestHandler(request, client_address, server)
 
@@ -537,5 +537,5 @@ default :class:`BaseHTTPRequestHandler` ``.log_message``
 implementation. This could allow remote clients connecting to your
 server to send nefarious control codes to your terminal.
 
-.. versionadded:: 3.12
+.. versionchanged:: 3.12
    Control characters are scrubbed in stderr logs.

Doc/library/logging.config.rst

@@ -127,8 +127,8 @@ in :mod:`logging` itself) and defining handlers which are declared either in
         application (e.g. based on command-line parameters or other aspects
         of the runtime environment) before being passed to ``fileConfig``.
 
-    .. versionadded:: 3.10
-       The *encoding* parameter is added.
+    .. versionchanged:: 3.10
+       Added the *encoding* parameter.
 
     .. versionchanged:: 3.12
        An exception will be thrown if the provided file

Doc/library/logging.handlers.rst

@@ -871,8 +871,8 @@ supports sending logging messages to an email address via SMTP.
    A timeout can be specified for communication with the SMTP server using the
    *timeout* argument.
 
-   .. versionadded:: 3.3
-      The *timeout* argument was added.
+   .. versionchanged:: 3.3
+      Added the *timeout* parameter.
 
    .. method:: emit(record)
 

Doc/library/logging.rst

@@ -615,14 +615,14 @@ Formatter Objects
        ``logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})``
    :type defaults: dict[str, Any]
 
-   .. versionadded:: 3.2
-      The *style* parameter.
+   .. versionchanged:: 3.2
+      Added the *style* parameter.
 
-   .. versionadded:: 3.8
-      The *validate* parameter.
+   .. versionchanged:: 3.8
+      Added the *validate* parameter.
 
-   .. versionadded:: 3.10
-      The *defaults* parameter.
+   .. versionchanged:: 3.10
+      Added the *defaults* parameter.
 
 
    .. method:: format(record)

Doc/library/multiprocessing.shared_memory.rst

@@ -88,8 +88,8 @@ copying of data.
       *track* is ignored on Windows, which has its own tracking and
       automatically deletes shared memory when all handles to it have been closed.
 
-   .. versionadded:: 3.13
-      The *track* parameter.
+   .. versionchanged:: 3.13
+      Added the *track* parameter.
 
    .. method:: close()