[3.13] gh-130536: Add details to `os.path` documentation (GH-130557) (#142801)

Co-authored-by: Arthur Wigo <arthur.l.wigo@gmail.com>

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index e8a9de5cadb91589bace63f71de1e571d2f5214c..b07d346caf499d455381f04c578422524f358a40 100644 (file)
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -57,8 +57,9 @@ the :mod:`glob` module.)
 .. function:: abspath(path)
 
    Return a normalized absolutized version of the pathname *path*. On most
-   platforms, this is equivalent to calling the function :func:`normpath` as
-   follows: ``normpath(join(os.getcwd(), path))``.
+   platforms, this is equivalent to calling ``normpath(join(os.getcwd(), path))``.
+
+   .. seealso:: :func:`os.path.join` and :func:`os.path.normpath`.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -243,6 +244,8 @@ the :mod:`glob` module.)
    begins with a slash, on Windows that it begins with two (back)slashes, or a
    drive letter, colon, and (back)slash together.
 
+   .. seealso:: :func:`abspath`
+
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
@@ -357,14 +360,28 @@ the :mod:`glob` module.)
    concatenation of *path* and all members of *\*paths*, with exactly one
    directory separator following each non-empty part, except the last. That is,
    the result will only end in a separator if the last part is either empty or
-   ends 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.
+   ends 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 Linux, for example::
+
+      >>> os.path.join('/home/foo', 'bar')
+      '/home/foo/bar'
+      >>> os.path.join('/home/foo', '/home/bar')
+      '/home/bar'
 
    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,
+   absolute path, all previous segments are ignored and the drive is reset. For
+   example::
+
+      >>> os.path.join('c:\\', 'foo')
+      'c:\\foo'
+      >>> os.path.join('c:\\foo', 'd:\\bar')
+      'd:\\bar'
+
+   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`.
 
@@ -518,8 +535,8 @@ the :mod:`glob` module.)
    *path* is empty, both *head* and *tail* are empty.  Trailing slashes are
    stripped from *head* unless it is the root (one or more slashes only).  In
    all cases, ``join(head, tail)`` returns a path to the same location as *path*
-   (but the strings may differ).  Also see the functions :func:`dirname` and
-   :func:`basename`.
+   (but the strings may differ).  Also see the functions :func:`join`,
+   :func:`dirname` and :func:`basename`.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.