`shlex.join`'s docstring isn't sufficiently clear

[BenFrantzDale]

Documentation

I had been using " ".join(shlex.escape(x) for x in args), not realizing that shlex.join(args) is exactly that.

The docstring is just """Return a shell-escaped string from *split_command*.""". I'd like to see something like

    """
    Return a shell-escaped string from *split_command*.
    That is, given a list of strings, return a string that, when printed,
    can be copy-pasted into a shell and provide an argc of len(split_command).
    
    For example:
    >>> print(shlex.join(['echo', 'foo \"bar\" baz']))
    echo 'foo "bar" baz'
    >>>
    $ echo 'foo "bar" baz'
    foo "bar" baz
    $
    """

Linked PRs

• gh-142895: Improve shlex.join documentation #142914

[picnixz]

Are the online docs inaccurate? I prefer updating the online docs rather than the docstring. Docstrings are usually shorter and less complete than online docs.

[BenFrantzDale]

As a user, I go to the docstrings. I didn't know there was separate documentation. (I feel like numpy has most of its docs in docstrings...)