gh-142895: Improve shlex.join docstring

Expand the terse docstring for shlex.join() to explain that it is
the inverse of split() and that the result is shell-escaped. Add
doctest examples showing round-trip behavior.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kovan

Lib/shlex.py

@@ -313,7 +313,18 @@ def split(s, comments=False, posix=True):
 
 
 def join(split_command):
-    """Return a shell-escaped string from *split_command*."""
+    """Concatenate the tokens of the list *split_command* and return a string.
+
+    This is the inverse of :func:`split`: the returned value is
+    shell-escaped to protect against injection, so the split of the
+    result equals *split_command*.
+
+        >>> from shlex import split, join
+        >>> split('echo "hello world"')
+        ['echo', 'hello world']
+        >>> join(['echo', 'hello world'])
+        "echo 'hello world'"
+    """
     return ' '.join(quote(arg) for arg in split_command)