Merge from 3.2 (#10318, #12255, #12043, #12417 and other fixes)

1 files changed, 16 insertions, 10 deletions

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index f8a1b60..799230c 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -159,12 +159,18 @@ Directory and files operations
 
 .. function:: move(src, dst)
 
-   Recursively move a file or directory to another location.
+   Recursively move a file or directory (*src*) to another location (*dst*).
 
-   Uses :func:`os.rename` to perform the move. If it fails, for reasons such as
-   when *src* and *dst* are on different filesystems or in case of windows where
-   rename is not supported when *dst* exists, fallback to copying *src* (with
-   :func:`copy2`) to the *dst* and then remove *src*.
+   If the destination is a directory or a symlink to a directory, then *src* is
+   moved inside that directory.
+
+   The destination directory must not already exist.  If the destination already
+   exists but is not a directory, it may be overwritten depending on
+   :func:`os.rename` semantics.
+
+   If the destination is on the current filesystem, then :func:`os.rename` is
+   used.  Otherwise, *src* is copied (using :func:`copy2`) to *dst* and then
+   removed.
 
 .. function:: disk_usage(path)
 
@@ -177,9 +183,9 @@ Directory and files operations
 
 .. exception:: Error
 
-   This exception collects exceptions that raised during a multi-file operation. For
-   :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
-   *dstname*, *exception*).
+   This exception collects exceptions that are raised during a multi-file
+   operation. For :func:`copytree`, the exception argument is a list of 3-tuples
+   (*srcname*, *dstname*, *exception*).
 
 
 .. _shutil-example:
@@ -277,7 +283,7 @@ Archiving operations
 
 .. function:: get_archive_formats()
 
-   Returns a list of supported formats for archiving.
+   Return a list of supported formats for archiving.
    Each element of the returned sequence is a tuple ``(name, description)``
 
    By default :mod:`shutil` provides these formats:
@@ -295,7 +301,7 @@ Archiving operations
 
 .. function:: register_archive_format(name, function, [extra_args, [description]])
 
-   Registers an archiver for the format *name*. *function* is a callable that
+   Register an archiver for the format *name*. *function* is a callable that
    will be used to invoke the archiver.
 
    If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be