[docs] [issue37970] urllib.parse docstrings incomplete

[Zachary Ware]

Zachary Ware <zachary.ware at gmail.com> added the comment:

I see.  I don't think we need to describe each returned component in the docstring; they're some combination of self-explanatory, described in the reference docs, or just industry-standard terms that are easily defined from other sources.  I'm not suggesting to add anything to the docstring about the `scheme` return component, but rather the *scheme* argument (which is the default value for the `scheme` return component when it's not found in the *url*).  The subcomponents of netloc should be mentioned because the docstring currently gives the impression that the user has to parse them out for themselves, which is not true.

Off the top of my head, I'd suggest changing the `urlsplit` docstring to something like:

```
Parse *url* and return a SplitResult.

SplitResult is a named 5-tuple of the following components:
<scheme>://<netloc>/<path>?<query>#<fragment>

The ``username``, ``password``, ``hostname``, and ``port``
sub-components of ``netloc`` can also be accessed as
attributes of the SplitResult object.

The *scheme* argument provides the default value of the
``scheme`` component when no scheme is found in *url*.

If *allow_fragments* is False, no attempt is made to
separate the ``fragment`` component from the previous
component, which can be either ``path`` or ``query``.

Note that % escapes are not expanded.
```

----------
nosy: +orsenthil

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37970>
_______________________________________