diff --git a/lib/std/core/builtin.c3 b/lib/std/core/builtin.c3
index c8d0887b3..b0e05c97f 100644
--- a/lib/std/core/builtin.c3
+++ b/lib/std/core/builtin.c3
@@ -451,11 +451,24 @@ macro @prefetch(void* ptr, PrefetchLocality $locality = VERY_NEAR, bool $write =
 	$endif
 }
 
+<*
+ Shuffle a vector by its index
+ 
+ int[<4>] a = { 1, 2, 3, 4 };
+ assert(swizzle(a, 0, 1, 1, 3) == (int[<4>]) { 1, 2, 2, 4 });
+*>
 macro swizzle(v, ...) @builtin
 {
 	return $$swizzle(v, $vasplat);
 }
 
+<*
+ Shuffle two vectors by a common index from arranging the vectors sequentially in memory
+
+ int[<4>] a = { 1, 2, 3, 4 };
+ int[<4>] b = { 100, 1000, 10000, 100000 };
+ assert(swizzle2(a, b, 0, 1, 4, 6, 2) == (int[<5>]) { 1, 2, 100, 10000, 3 });
+*>
 macro swizzle2(v, v2, ...) @builtin
 {
 	return $$swizzle2(v, v2, $vasplat);