From 1e77f38d10eff6cc707b8c2721d87d8d24c3b914 Mon Sep 17 00:00:00 2001
From: Kodi Arfer <git@arfer.net>
Date: Tue, 13 Aug 2019 16:55:21 -0400
Subject: [PATCH] Expand the documentation of `setv`

---
 docs/language/api.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/language/api.rst b/docs/language/api.rst
index b357c48..c4f877b 100644
--- a/docs/language/api.rst
+++ b/docs/language/api.rst
@@ -424,20 +424,19 @@ For example:
     => (counter [1 2 3 4 5 2 3] 2)
     2
 
-They can be used to assign multiple variables at once:
+You can provide more than one target–value pair, and the assignments will be made in order::
 
-.. code-block:: hy
+    (setv  x 1  y x  x 2)
+    (print x y)  ; => 2 1
 
-    => (setv a 1 b 2)
-    (1L, 2L)
-    => a
-    1L
-    => b
-    2L
-    =>
+You can perform parallel assignments or unpack the source value with square brackets and :ref:`unpack-iterable`::
 
+    (setv duo ["tim" "eric"])
+    (setv [guy1 guy2] duo)
+    (print guy1 guy2)  ; => tim eric
 
-``setv`` always returns ``None``.
+    (setv [letter1 letter2 #* others] "abcdefg")
+    (print letter1 letter2 others)   ; => a b ['c', 'd', 'e', 'f', 'g']
 
 
 setx