[3.11] GH-105900: Fix `pathlib.Path.symlink_to(target_is_directory=...)` docs (GH...

Clarify that *target_is_directory* only matters if the target doesn't
exist.
(cherry picked from commit b822b85ac11e73bbe4417bf03ee770ab116bb42d)

Co-authored-by: Barney Gale <barney.gale@gmail.com>

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 528236cfa7eaa6d18add1b7de5daccf18e6a3239..4c3edcb6361007d16835431b0a39f8782e71c3d8 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1187,9 +1187,13 @@ call fails (for example because the path doesn't exist).
 
 .. method:: Path.symlink_to(target, target_is_directory=False)
 
-   Make this path a symbolic link to *target*.  Under Windows,
-   *target_is_directory* must be true (default ``False``) if the link's target
-   is a directory.  Under POSIX, *target_is_directory*'s value is ignored.
+   Make this path a symbolic link pointing to *target*.
+
+   On Windows, a symlink represents either a file or a directory, and does not
+   morph to the target dynamically.  If the target is present, the type of the
+   symlink will be created to match. Otherwise, the symlink will be created
+   as a directory if *target_is_directory* is ``True`` or a file symlink (the
+   default) otherwise.  On non-Windows platforms, *target_is_directory* is ignored.
 
    ::