gh-82151: Improve docs for urllib.parse

Doc/library/urllib.parse.rst

@@ -37,16 +37,18 @@ URL Parsing
 The URL parsing functions focus on splitting a URL string into its components,
 or on combining URL components into a URL string.
 
-.. function:: urlparse(urlstring, scheme='', allow_fragments=True)
+.. function:: urlparse(url, scheme='', allow_fragments=True)
 
    Parse a URL into six components, returning a 6-item :term:`named tuple`.  This
    corresponds to the general structure of a URL:
    ``scheme://netloc/path;parameters?query#fragment``.
-   Each tuple item is a string, possibly empty. The components are not broken up
-   into smaller parts (for example, the network location is a single string), and %
-   escapes are not expanded. The delimiters as shown above are not part of the
-   result, except for a leading slash in the *path* component, which is retained if
-   present.  For example:
+
+   Each tuple item is a string, possibly empty. The components are broken up into
+   smaller parts (for example, the components of the network location variable -
+   username, password, hostname, and port - are available as extra attributes in the
+   ParseResult/ParseResultBytes object). % escapes are not expanded.
+   The delimiters as shown above are not part of the result, except for a leading slash
+   in the *path* component, which is retained if present.  For example:
 
       >>> from urllib.parse import urlparse
       >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
@@ -81,7 +83,7 @@ or on combining URL components into a URL string.
 
    The *scheme* argument gives the default addressing scheme, to be
    used only if the URL does not specify one.  It should be the same type
-   (text or bytes) as *urlstring*, except that the default value ``''`` is
+   (text or bytes) as *url*, except that the default value ``''`` is
    always allowed, and is automatically converted to ``b''`` if appropriate.
 
    If the *allow_fragments* argument is false, fragment identifiers are not
@@ -245,9 +247,11 @@ or on combining URL components into a URL string.
    states that these are equivalent).
 
 
-.. function:: urlsplit(urlstring, scheme='', allow_fragments=True)
+.. function:: urlsplit(url, scheme='', allow_fragments=True)
 
-   This is similar to :func:`urlparse`, but does not split the params from the URL.
+   This is similar to :func:`urlparse`, the returned SplitResult/SplitResultBytes object
+   will split the parameters from the URL, for example, the components of the network location
+   variable - username, password, hostname, and port - are available as extra attributes.
    This should generally be used instead of :func:`urlparse` if the more recent URL
    syntax allowing parameters to be applied to each segment of the *path* portion
    of the URL (see :rfc:`2396`) is wanted.  A separate function is needed to