gh-142895: Improve shlex.join documentation

Lib/shlex.py

@@ -313,7 +313,14 @@ def split(s, comments=False, posix=True):
 
 
 def join(split_command):
-    """Return a shell-escaped string from *split_command*."""
+    """Return a shell-escaped string from *split_command*.
+
+    This function is the inverse of :func:`split`.
+
+    >>> import shlex
+    >>> print(shlex.join(['echo', '-n', 'Multiple words']))
+    echo -n 'Multiple words'
+    """
     return ' '.join(quote(arg) for arg in split_command)
 
 

Misc/NEWS.d/next/Library/2025-12-17-20-55-24.gh-issue-142895.HKofui.rst

@@ -0,0 +1 @@
+Add examples to :func:`shlex.join` docstring.