Issue #15414: Clean and correct the os.path.join docs.

In particular, correctly describe the behavior of ntpath.join.

Based on a patch by Dave Sawyer.

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index dc03f4342281ccc878d705f3e15fea7841fb26f9..92631b2e416da295093e6fdf30cf9546ac5f8005 100644 (file)
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -206,17 +206,22 @@ the :mod:`glob` module.)
       Support for detecting non-root mount points on Windows.
 
 
-.. function:: join(path1[, path2[, ...]])
-
-   Join one or more path components intelligently.  If any component is an absolute
-   path, all previous components (on Windows, including the previous drive letter,
-   if there was one) are thrown away, and joining continues.  The return value is
-   the concatenation of *path1*, and optionally *path2*, etc., with exactly one
-   directory separator (``os.sep``) following each non-empty part except the last.
-   (This means that an empty last part will result in a path that ends with a
-   separator.)  Note that on Windows, since there is a current directory for
-   each drive, ``os.path.join("c:", "foo")`` represents a path relative to the
-   current directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
+.. function:: join(path, *paths)
+
+   Join one or more path components intelligently.  The return value is the
+   concatenation of *path* and any members of *\*paths* with exactly one
+   directory separator (``os.sep``) following each non-empty part except the
+   last, meaning that the result will only end in a separator if the last
+   part is empty.  If a component is an absolute path, all previous
+   components are thrown away and joining continues from the absolute path
+   component.
+
+   On Windows, the drive letter is not reset when an absolute path component
+   (e.g., ``r'\foo'``) is encountered.  If a component contains a drive
+   letter, all previous components are thrown away and the drive letter is
+   reset.  Note that since there is a current directory for each drive,
+   ``os.path.join("c:", "foo")`` represents a path relative to the current
+   directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
 
 
 .. function:: normcase(path)