Improves ARGFILES with examples, refs #96

doc/Type/IO/ArgFiles.pod6

@@ -7,13 +7,27 @@
    class IO::ArgFiles is IO::CatHandle { }
 
 This class exists for backwards compatibility reasons and provides no methods.
-All the functionality is inherited from L<IO::CatHandle>.
+All the functionality is inherited from L<IO::CatHandle>. It can be used, for
+instance, this way:
+
+=for code
+my $argfiles = IO::ArgFiles.new(@*ARGS);
+.say for $argfiles.lines;
+
+If invoked with C<perl6 io-argfiles.p6 *.p6> it will print the contents of all
+the files with that extension in the directory. However, that is totally
+equivalent to:
+
+=for code
+my $argfiles = IO::CatHandle.new(@*ARGS);
+.say for $argfiles.lines;
+
 
 =head1 Variables
 
 =head2 C<$*ARGFILES>
 
-This class is the magic behind the C<$*ARGFILES> variable.  This variable
+This class is the magic behind the C<$*ARGFILES> variable, which
 provides a way to iterate over files passed in to the program on the command
 line (i.e. elements of L<C«@*ARGS»|/language/variables#index-entry-%40%2AARGS>).
 Thus the examples above can be simplified like so:
@@ -46,7 +60,24 @@ Shall I compare thee to a summer's day?
 
 As of 6.d language, C<$*ARGFILES> I<inside>
 L<C«sub MAIN»|/language/functions#sub_MAIN> is always set to C<$*IN>, even
-when C<@*ARGS> is not empty.
+when C<@*ARGS> is not empty. That means that
+
+=for code
+sub MAIN () {
+    .say for $*ARGFILES.lines;
+}
+
+which can be used as C<cat *.p6 | perl6 argfiles-main.p6>, for instance, is
+totally equivalent to:
+
+=for code
+sub MAIN () {
+    .say for $*IN.lines;
+}
+
+and, in fact, can't be used to process the arguments in the command line, since,
+in this case, it would result in an usage error.
+
 
 =end pod