[DOC] Doc for StringIO#each_byte

ext/stringio/stringio.c

@@ -937,9 +937,41 @@ strio_get_sync(VALUE self)
  *   each_byte {|byte| ... } -> self
  *
  * With a block given, calls the block with each remaining byte in the stream;
- * see {Byte IO}[rdoc-ref:IO@Byte+IO].
- *
- * With no block given, returns an enumerator.
+ * positions the stream at end-of-file;
+ * returns +self+:
+ *
+ *   bytes = []
+ *   strio = StringIO.new('hello')     #  Five 1-byte characters.
+ *   strio.each_byte {|byte| bytes.push(byte) }
+ *   strio.eof? # => true
+ *   bytes # => [104, 101, 108, 108, 111]
+ *   bytes = []
+ *   strio = StringIO.new('тест')      # Four 2-byte characters.
+ *   strio.each_byte {|byte| bytes.push(byte) }
+ *   bytes # => [209, 130, 208, 181, 209, 129, 209, 130]
+ *   bytes = []
+ *   strio = StringIO.new('こんにちは')  # Five 3-byte characters.
+ *   strio.each_byte {|byte| bytes.push(byte) }
+ *   bytes # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
+ *
+ * The position in the stream matters:
+ *
+ *   bytes = []
+ *   strio = StringIO.new('こんにちは')
+ *   strio.getc # => "こ"
+ *   strio.pos  # => 3  # 3-byte character was read.
+ *   strio.each_byte {|byte| bytes.push(byte) }
+ *   bytes      # => [227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
+ *
+ * If at end-of-file, does not call the block:
+ *
+ *   strio.eof? # => true
+ *   strio.each_byte {|byte| fail 'Boo!' }
+ *   strio.eof? # => true
+ *
+ * With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
+ *
+ * Related: StringIO#each_char, StringIO#each_codepoint, StringIO#each_line.
  */
 static VALUE
 strio_each_byte(VALUE self)
@@ -1630,7 +1662,7 @@ strio_readline(int argc, VALUE *argv, VALUE self)
  * "Fifth line"
  * ```
  *
- * With no block given, returns a new  {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
+ * With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html].
  *
  * Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.
  */