From 63ca40c6b093884c53f7491595e44d6aefefc06f Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@raku.rocks>
Date: Tue, 7 Mar 2023 20:28:14 +0100
Subject: [PATCH] Document .pick(**)

---
 doc/Type/List.rakudoc | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/Type/List.rakudoc b/doc/Type/List.rakudoc
index d8263eb9c..c095982ad 100644
--- a/doc/Type/List.rakudoc
+++ b/doc/Type/List.rakudoc
@@ -737,6 +737,7 @@ against a L<Signature|/type/Signature>.
 
     multi sub    pick($count, *@list --> Seq:D)
     multi method pick(List:D: $count --> Seq:D)
+    multi method pick(List:D: * --> Seq:D)
     multi method pick(List:D: --> Mu)
 
 If C<$count> is supplied: Returns C<$count> elements chosen at random
@@ -754,6 +755,16 @@ Examples:
     say <a b c d e>.pick: 3;        # OUTPUT: «(c a e)␤»
     say <a b c d e>.pick: *;        # OUTPUT: «(e d a b c)␤»
 
+As of the 2021.06 release of the Rakudo compiler, it is also possible to
+specify C<**> (aka C<HyperWhatever>) as the count.
+
+    multi method pick(List:D: ** --> Seq:D)
+
+In that case, C<.pick> will start picking again on the original list
+after it has been exhausted, again and again, indefinitely.
+
+    say <a b c>.pick(**).head(10);  # OUTPUT: «((a c b c a b b c a b))␤»
+
 =head2 routine roll
 
     multi sub    roll($count, *@list --> Seq:D)