Improve pathname2url() and url2pathname() docs

Doc/library/urllib.request.rst

@@ -148,9 +148,14 @@ The :mod:`urllib.request` module defines the following functions:
 
 .. function:: pathname2url(path)
 
-   Convert the pathname *path* from the local syntax for a path to the form used in
-   the path component of a URL.  This does not produce a complete URL.  The return
-   value will already be quoted using the :func:`~urllib.parse.quote` function.
+   Convert the given local path to a ``file:`` URL. This function uses
+   :func:`~urllib.parse.quote` function to encode the path. For historical
+   reasons, the return value omits the ``file:`` scheme prefix. For example::
+
+      >>> from urllib.request import pathname2url
+      >>> path = 'C:\\Windows'
+      >>> 'file:' + pathname2url(path)
+      'file:///C:/Windows'
 
    .. versionchanged:: 3.14
       Windows drive letters are no longer converted to uppercase.
@@ -161,11 +166,16 @@ The :mod:`urllib.request` module defines the following functions:
       found in any position other than the second character.
 
 
-.. function:: url2pathname(path)
+.. function:: url2pathname(url)
+
+   Convert the given ``file:`` URL to a local path. This function uses
+   :func:`~urllib.parse.unquote` to decode the URL. For historical reasons,
+   the given URL *must* omit the ``file:`` scheme prefix. For example::
 
-   Convert the path component *path* from a percent-encoded URL to the local syntax for a
-   path.  This does not accept a complete URL.  This function uses
-   :func:`~urllib.parse.unquote` to decode *path*.
+      >>> from urllib.request import url2pathname
+      >>> url = 'file:///C:/Windows'
+      >>> url2pathname(url.removeprefix('file:'))
+      'C:\\Windows'
 
    .. versionchanged:: 3.14
       Windows drive letters are no longer converted to uppercase.