From c3c116f6a6b92d0224b35e7423959a7ab39ddc6b Mon Sep 17 00:00:00 2001
From: Victor Shepelev <zverok.offline@gmail.com>
Date: Sat, 24 Dec 2022 00:48:58 +0200
Subject: [DOC] Document new methods of IO::Buffer and Fiber::Scheduler (#7016)

Co-authored-by: Samuel Williams <samuel.williams@oriontransfer.co.nz>
---
 io_buffer.c | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 69 insertions(+), 10 deletions(-)

(limited to 'io_buffer.c')

diff --git a/io_buffer.c b/io_buffer.c
index d866c967b7..c5f0b193c3 100644
--- a/io_buffer.c
+++ b/io_buffer.c
@@ -2415,10 +2415,10 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset)
 }
 
 /*
- *  call-seq: read(io, [length, [offset]]) -> self
+ *  call-seq: read(io, [length, [offset]]) -> read length or -errno
  *
  *  Read at most +length+ bytes from +io+ into the buffer, starting at
- *  +offset+.
+ *  +offset+. If an error occurs, return <tt>-errno</tt>.
  *
  *  If +length+ is not given, read until the end of the buffer.
  *
@@ -2428,14 +2428,17 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset)
  *
  *  Example:
  *
- *    buffer = IO::Buffer.for('test')
- *    # =>
- *    # <IO::Buffer 0x00007fca40087c38+4 SLICE>
- *    # 0x00000000  74 65 73 74         test
- *    buffer.read(File.open('/dev/urandom', 'rb'), 4)
- *    # =>
- *    # <IO::Buffer 0x00007fca40087c38+4 SLICE>
- *    # 0x00000000  2a 0e 0e 0e         *...
+ *    IO::Buffer.for('test') do |buffer|
+ *      p buffer
+ *      # =>
+ *      # <IO::Buffer 0x00007fca40087c38+4 SLICE>
+ *      # 0x00000000  74 65 73 74         test
+ *      buffer.read(File.open('/dev/urandom', 'rb'), 2)
+ *      p buffer
+ *      # =>
+ *      # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE>
+ *      # 0x00000000  05 35 73 74         .5st
+ *    end
  */
 static VALUE
 io_buffer_read(int argc, VALUE *argv, VALUE self)
@@ -2536,6 +2539,32 @@ rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t of
     return rb_thread_io_blocking_region(io_buffer_pread_internal, &argument, descriptor);
 }
 
+/*
+ *  call-seq: pread(io, from, length, [offset]) -> read length or -errno
+ *
+ *  Read at most +length+ bytes from +io+ into the buffer, starting at
+ *  +from+, and put it in buffer starting from specified +offset+.
+ *  If an error occurs, return <tt>-errno</tt>.
+ *
+ *  If +offset+ is not given, put it at the beginning of the buffer.
+ *
+ *  Example:
+ *
+ *    IO::Buffer.for('test') do |buffer|
+ *      p buffer
+ *      # =>
+ *      # <IO::Buffer 0x00007fca40087c38+4 SLICE>
+ *      # 0x00000000  74 65 73 74         test
+ *
+ *      # take 2 bytes from the beginning of urandom,
+ *      # put them in buffer starting from position 2
+ *      buffer.pread(File.open('/dev/urandom', 'rb'), 0, 2, 2)
+ *      p buffer
+ *      # =>
+ *      # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE>
+ *      # 0x00000000  05 35 73 74         te.5
+ *    end
+ */
 static VALUE
 io_buffer_pread(int argc, VALUE *argv, VALUE self)
 {
@@ -2610,6 +2639,20 @@ rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset)
     return rb_thread_io_blocking_region(io_buffer_write_internal, &argument, descriptor);
 }
 
+/*
+ *  call-seq: write(io, length, [offset]) -> written length or -errno
+ *
+ *  Writes +length+ bytes from buffer into +io+, starting at
+ *  +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>.
+ *
+ *  If +offset+ is not given, the bytes are taken from the beginning
+ *  of the buffer.
+ *
+ *    out = File.open('output.txt', 'wb')
+ *    IO::Buffer.for('1234567').write(out, 3)
+ *
+ *  This leads to +123+ being written into <tt>output.txt</tt>
+ */
 static VALUE
 io_buffer_write(int argc, VALUE *argv, VALUE self)
 {
@@ -2709,6 +2752,22 @@ rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t o
     return rb_thread_io_blocking_region(io_buffer_pwrite_internal, &argument, descriptor);
 }
 
+/*
+ *  call-seq: pwrite(io, from, length, [offset]) -> written length or -errno
+ *
+ *  Writes +length+ bytes from buffer into +io+, starting at
+ *  +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>.
+ *
+ *  If +offset+ is not given, the bytes are taken from the beginning of the
+ *  buffer. If the +offset+ is given and is beyond the end of the file, the
+ *  gap will be filled with null (0 value) bytes.
+ *
+ *    out = File.open('output.txt', File::RDWR) # open for read/write, no truncation
+ *    IO::Buffer.for('1234567').pwrite(out, 2, 3, 1)
+ *
+ *  This leads to +234+ (3 bytes, starting from position 1) being written into
+ *  <tt>output.txt</tt>, starting from file position 2.
+ */
 static VALUE
 io_buffer_pwrite(int argc, VALUE *argv, VALUE self)
 {
-- 
cgit v1.2.3