diff -r 5fd9b87e08b3 Doc/library/os.rst
--- a/Doc/library/os.rst	Wed Nov 07 23:54:37 2012 +0100
+++ b/Doc/library/os.rst	Wed Nov 21 23:51:59 2012 -0500
@@ -1720,18 +1720,38 @@
 
 .. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
 
-   Rename the file or directory *src* to *dst*.  If *dst* is a directory,
-   :exc:`OSError` will be raised.  On Unix, if *dst* exists and is a file, it will
-   be replaced silently if the user has permission.  The operation may fail on some
-   Unix flavors if *src* and *dst* are on different filesystems.  If successful,
-   the renaming will be an atomic operation (this is a POSIX requirement).  On
-   Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
-   file.
+   Rename the file or directory *src* to *dst*. If *src* exists as either
+   a file or directory and *dst* does not exist the rename will occur with
+   no error raised.  In some cases the rename function will behave
+   differently across platforms which are noted below. In all cases
+   if *src* does not exist :exc:`OSError` will be raised.
+
+   Unix
+      If *dst* exists and is a file, it will be replaced silently if the user
+      has permission and src is a file.  If *src* is a directory and *dst* is a
+      file :exc:`OSError` will be raised.  In the case where *src* is a
+      directory and *dst* is a empty directory the rename will occur and the
+      *src* directory name will overwrite the *dst* directory name.Yet a
+      special case is noted where *src* is a directory and *dst* is a
+      non-empty directory the rename will not occur and :exc:`OSError`
+      will be raised.
+
+   Windows
+      If *src* is a file and *dst* exists either as a file or directory
+      :exc:`OSError` will be raised and the rename will not occur.  In the
+      case where *src* is a directory, either empty or not empty, and *dst*
+      exists as a file or not empty directory :exc:`OSError` will be raised.
+      If *src* is a directory, either empty or not empty, and *dst* is a empty
+      directory then :exc:`FileExistsError` will be raised.
+
+   If successful, the renaming will be an atomic operation (this is a POSIX
+   requirement).
 
    This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
    supply :ref:`paths relative to directory descriptors <dir_fd>`.
 
-   If you want cross-platform overwriting of the destination, use :func:`replace`.
+   If you want cross-platform overwriting of the destination, use
+   :func:`replace`.
 
    Availability: Unix, Windows.