#9921: clarify os.path.join joining algorithm

The new wording is based on the comments in the code, which
match the actual behavior.

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 4867e8b211f3f32581f04d296c7c792c1436b881..62bbdfff70d0f7f29937e67bda79f681b1a5aaf3 100644 (file)
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -196,10 +196,11 @@ write files see :func:`open`, and for accessing the filesystem see the
    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``) inserted between components, unless *path2* is
-   empty.  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`.
+   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:: normcase(path)