From 1d2a07f4e8e5ee592103d3d8c40f349d672d99eb Mon Sep 17 00:00:00 2001
From: Ali Faraji <ali@faraji.info>
Date: Wed, 17 Dec 2025 20:56:39 -0500
Subject: [PATCH] gh-142895: Improve shlex.join documentation

---
 Lib/shlex.py                                             | 9 ++++++++-
 .../2025-12-17-20-55-24.gh-issue-142895.HKofui.rst       | 1 +
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Library/2025-12-17-20-55-24.gh-issue-142895.HKofui.rst

diff --git a/Lib/shlex.py b/Lib/shlex.py
index 5959f52dd12639..5c23aaa0f6e588 100644
--- a/Lib/shlex.py
+++ b/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)
 
 
diff --git a/Misc/NEWS.d/next/Library/2025-12-17-20-55-24.gh-issue-142895.HKofui.rst b/Misc/NEWS.d/next/Library/2025-12-17-20-55-24.gh-issue-142895.HKofui.rst
new file mode 100644
index 00000000000000..58d379a16b9dd3
--- /dev/null
+++ b/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.