From 2f678e343389b25c49821c1034b52870e2a17981 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 25 Sep 2024 22:16:14 -0700
Subject: [PATCH] gh-119127: functools: Improve docs for partial and
 Placeholder

Edits for improving the clarity and writing of the docs for partial.
---
 Doc/library/functools.rst | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 774b3262117723..fa04183dd51db7 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -354,7 +354,7 @@ The :mod:`functools` module defines the following functions:
           newfunc.keywords = keywords
           return newfunc
 
-   The :func:`partial` function is used for partial function application which "freezes"
+   The :func:`!partial` function is used for partial function application which "freezes"
    some portion of a function's arguments and/or keywords resulting in a new object
    with a simplified signature.  For example, :func:`partial` can be used to create
    a callable that behaves like the :func:`int` function where the *base* argument
@@ -368,10 +368,11 @@ The :mod:`functools` module defines the following functions:
       18
 
    If :data:`Placeholder` sentinels are present in *args*, they will be filled first
-   when :func:`partial` is called. This allows custom selection of positional arguments
-   to be pre-filled when constructing a :ref:`partial object <partial-objects>`.
+   when :func:`!partial` is called. This makes it possible to pre-fill any positional
+   argument with a call to :func:`!partial`; without :data:`!Placeholder`, only the
+   first positional argument can be pre-filled.
 
-   If :data:`!Placeholder` sentinels are present, all of them must be filled at call time:
+   If any :data:`!Placeholder` sentinels are present, all must be filled at call time:
 
    .. doctest::
 
@@ -379,14 +380,15 @@ The :mod:`functools` module defines the following functions:
       >>> say_to_world('Hello', 'dear')
       Hello dear world!
 
-   Calling ``say_to_world('Hello')`` would raise a :exc:`TypeError`, because
-   only one positional argument is provided, while there are two placeholders
-   in :ref:`partial object <partial-objects>`.
+   Calling ``say_to_world('Hello')`` raises a :exc:`TypeError`, because
+   only one positional argument is provided, but there are two placeholders
+   that must be filled in.
 
-   Successive :func:`partial` applications fill :data:`!Placeholder` sentinels
-   of the input :func:`partial` objects with new positional arguments.
-   A place for positional argument can be retained by inserting new
-   :data:`!Placeholder` sentinel to the place held by previous :data:`!Placeholder`:
+   If :func:`!partial` is applied to an existing :func:`!partial` object,
+   :data:`!Placeholder` sentinels of the input object are filled in with
+   new positional arguments.
+   A placeholder can be retained by inserting a new
+   :data:`!Placeholder` sentinel to the place held by a previous :data:`!Placeholder`:
 
    .. doctest::
 
@@ -402,8 +404,8 @@ The :mod:`functools` module defines the following functions:
       >>> remove_first_dear(message)
       'Hello, dear world!'
 
-   Note, :data:`!Placeholder` has no special treatment when used for keyword
-   argument of :data:`!Placeholder`.
+   :data:`!Placeholder` has no special treatment when used in a keyword
+   argument to :func:`!partial`.
 
    .. versionchanged:: 3.14
       Added support for :data:`Placeholder` in positional arguments.