gh-100783: fix os.path.join documentation (GH-100811)

- Use "drive", not "drive letter", because of UNC paths
- Previous components are not thrown away from relative drive letters
- Use "segment" instead of "component" for consistency with pathlib
- Other miscellaneous improvements
(cherry picked from commit 53455a319f3f2e5609fca2a313ea356fba318665)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 0becb592b41ee6c4d9da4f8c25eaed651324857c..319b664dd46d7975260ff465817112aacf480cf9 100644 (file)
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -297,17 +297,18 @@ the :mod:`glob` module.)
 
 .. 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 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,
+   Join one or more path segments intelligently.  The return value is the
+   concatenation of *path* and all members of *\*paths*, with exactly one
+   directory separator following each non-empty part except the last. That is,
+   if the last part is empty, the result will end in a separator. If
+   a segment is an absolute path (which on Windows requires both a drive and a
+   root), then all previous segments are ignored and joining continues from the
+   absolute path segment.
+
+   On Windows, the drive is not reset when a rooted path segment (e.g.,
+   ``r'\foo'``) is encountered. If a segment is on a different drive or is an
+   absolute path, all previous segments are ignored and the drive 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`.