Document IO::CatHandle.handles

Closes rakudo/rakudo#1546 R#1546
Spec:  Raku/roast@1a89a1e8f3
Impl:  rakudo/rakudo@d5baa036fa

doc/Type/IO/CatHandle.pod6

@@ -246,6 +246,42 @@ my $cat = IO::CatHandle.new: $f1, $f2;
 .say while $_ = $cat.getc; # OUTPUT: «I␤ ␤♥␤ ␤P␤e␤r␤l␤m␤e␤o␤w␤»
 =end code
 
+=head2 method handles
+
+Defines as:
+
+    method handles(IO::CatHandle:D: --> Seq:D)
+
+Returns a L<Seq> containing the currently-active handle, as well as all the
+remaining source handles produced by calling L<next-handle>. If the invocant
+has already been fully-consumed, returns an empty L<Seq>.
+
+This method is especially handy when working with L<IO::ArgFiles>, where you
+want to treat each filehandle separately:
+
+    # print at most the first 2 lines of each file in $*ARGFILES:
+    .say for flat $*ARGFILES.handles.map: *.lines: 2
+
+It I<is> acceptable to call this method multiple times and C<.handles.head> is a
+valid idiom for obtaining the currently-active handle. If, between
+L<reification|/language/glossary#index-entry-Reify> of the elements of the
+returned L<Seq> the handles get switched by some other means, the next
+element produced by the L<Seq> would be the next handle of the invocant, not
+the handle that would've been produced if no switching occured:
+
+    (my $file1 := 'file1'.IO).spurt: "1a\n1b\n1c";
+    (my $file2 := 'file2'.IO).spurt: "2a\n2b\n2c";
+    (my $file3 := 'file3'.IO).spurt: "3a\n3b\n3c";
+    my $cat := IO::CatHandle.new: $file1, $file2, $file3;
+    for $cat.handles {
+        say .lines: 2;
+        $cat.next-handle;
+    }
+    # OUTPUT: «(1a 1b)␤(3a 3b)␤»
+
+Likewise, reifying the returned L<Seq> consumes the invocant's source handles
+and once it is fully reified, the invocant becomes fully-consumed.
+
 =head2 method IO
 
 Defined as: