Document IO::Handle.READ/.WRITE/.EOF

Spec[^1] blocked by R#2039 rakudo/rakudo#2039

[^1] Raku/roast@3cefe0dc59

Author: zoffixznet

doc/Type/IO/Handle.pod6

@@ -908,6 +908,52 @@ Defined as:
 Returns C<True> if the handle is opened to a
 L<TTY|https://en.wikipedia.org/wiki/Terminal_emulator>, C<False> otherwise.
 
+=head1 Creating Custom Handles
+
+As of 6.d language (early implementation available in Rakudo compiler version 2018.07), a few
+helper methods are available to simplify creation of custom C<IO::Handle> objects. In your subclass
+you simply need to implement those methods to affect all of the related features.
+
+=head2 method WRITE
+
+Defined as:
+
+    method WRITE(IO::Handle:D: Blob:D \data --> Bool:D)
+
+Called whenever a write operation is performed on the handle. Always receives the data as a
+L<Blob>, even if a textual writing method has been called.
+
+=head2 method READ
+
+Defined as:
+
+    method READ(IO::Handle:D: Int:D \bytes --> Buf:D)
+
+Called whenever a read operation is performed on the handle. Receives the number of bytes
+requested to read. Returns a L<Buf> with those bytes which can be used to either fill the
+decoder buffer or returned from reading methods directly. The result is allowed to have fewer than
+the requested number of bytes, including no bytes at all.
+
+If you provide your own C<.READ>, you very likely need to provide your own
+L<C«.EOF»|/routine/EOF> as well, for all the features to behave correctly.
+
+The compiler may call L<C«.EOF»|/routine/EOF> method any number of times during a read operation to
+ascertain whether a call to C<.READ> should be made. More bytes than necessary to satisfy a read
+operation may be requested from C<.READ>, in which case the extra data may be buffered by
+the L<IO::Handle> or the decoder it's using, to fullfill any subsequent reading operations, without
+necessarilly having to make another C<.READ> call.
+
+=head2 method EOF
+
+Defined as:
+
+    method EOF(IO::Handle:D: --> Bool:D)
+
+Indicates wether "end of file" has been reached for the B<data source> of the handle; i.e. no more
+data can be obtained by calling L<C«.READ»|/routine/READ> method. Note that this is B<not> the
+same as L<eof> method, which will return C<True> only if C<.EOF> returns C<True> B<and all
+the decoder buffers>, if any were used by the handle, are also empty.
+
 =head1 Related roles and classes
 
 See also the related role L<IO> and the related class L<IO::Path>.