[io grant] Document new behaviour of IO::Handle.Supply

- Expand description
- Add examples

Author: zoffixznet

doc/Type/IO/Handle.pod6

@@ -235,13 +235,27 @@ otherwise the return will be a C<Str> with the optional encoding C<:enc>.
 
 =head2 method Supply
 
-    multi method Supply(IO::Handle:D: :$size = 65536, :$bin --> Supply)
+    multi method Supply(IO::Handle:D: :$size = 65536)
 
 Returns a C<Supply> that will emit the contents of the handle in chunks.
-The size of the chunks is determined by the optional C<:size> named parameter
-and defaults to 64K.  The optional C<:bin> named parameter can be specified
-to indicate binary reading of the contents, rather than character based
-reading.
+The chunks will be L«C<Buf>|/type/Buf» if the handle is in binary mode
+or, if it isn't, L«C<Str>|/type/Str» decoded using same encoding as L«C<IO::Handle.encoding>|/routine/encoding».
+
+The size of the chunks is determined by the optional C<:size> named
+parameter and C<65536> bytes in binary mode or C<65536> characters in non-binary
+mode.
+
+=for code :skip-test
+    "foo".IO.open(:bin).Supply(:size<10>).tap: *.perl.say;
+    # OUTPUT:
+    # Buf[uint8].new(73,32,226,153,165,32,80,101,114,108)
+    # Buf[uint8].new(32,54,33,10)
+
+    "foo".IO.open.Supply(:size<10>).tap: *.perl.say;
+    # OUTPUT:
+    # "I ♥ Perl 6"
+    # "!\n"
+
 
 =head2 method path