rbs 2.8.4 → 3.8.1

data/core/io/buffer.rbs

@@ -1,35 +1,37 @@
 %a{annotate:rdoc:skip}
 class IO
   # <!-- rdoc-file=io_buffer.c -->
-  # IO::Buffer is a low-level efficient buffer for input/output. There are three
-  # ways of using buffer:
+  # IO::Buffer is a efficient zero-copy buffer for input/output. There are typical
+  # use cases:
   #
-  # *   Create an empty buffer with ::new, fill it with data using #copy or
-  #     #set_value, #set_string, get data with #get_string;
+  # *   Create an empty buffer with ::new, fill it with buffer using #copy or
+  #     #set_value, #set_string, get buffer with #get_string or write it directly
+  #     to some file with #write.
   # *   Create a buffer mapped to some string with ::for, then it could be used
   #     both for reading with #get_string or #get_value, and writing (writing will
-  #     change the source string, too);
+  #     change the source string, too).
   # *   Create a buffer mapped to some file with ::map, then it could be used for
   #     reading and writing the underlying file.
-  #
+  # *   Create a string of a fixed size with ::string, then #read into it, or
+  #     modify it using #set_value.
   #
   # Interaction with string and file memory is performed by efficient low-level C
   # mechanisms like `memcpy`.
   #
   # The class is meant to be an utility for implementing more high-level
-  # mechanisms like Fiber::SchedulerInterface#io_read and
-  # Fiber::SchedulerInterface#io_write.
+  # mechanisms like Fiber::Scheduler#io_read and Fiber::Scheduler#io_write and
+  # parsing binary protocols.
   #
-  # **Examples of usage:**
+  # ## Examples of Usage
   #
   # Empty buffer:
   #
   #     buffer = IO::Buffer.new(8)  # create empty 8-byte buffer
-  #     #  =>
+  #     # =>
   #     # #<IO::Buffer 0x0000555f5d1a5c50+8 INTERNAL>
   #     # ...
   #     buffer
-  #     #  =>
+  #     # =>
   #     # <IO::Buffer 0x0000555f5d156ab0+8 INTERNAL>
   #     # 0x00000000  00 00 00 00 00 00 00 00
   #     buffer.set_string('test', 2) # put there bytes of the "test" string, starting from offset 2
@@ -40,32 +42,30 @@ class IO
   # Buffer from string:
   #
   #     string = 'data'
-  #     buffer = IO::Buffer.for(str)
-  #     #  =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # ...
-  #     buffer
-  #     #  =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # 0x00000000  64 61 74 61                                     data
+  #     IO::Buffer.for(string) do |buffer|
+  #       buffer
+  #       # =>
+  #       # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
+  #       # 0x00000000  64 61 74 61                                     data
   #
-  #     buffer.get_string(2)  # read content starting from offset 2
-  #     # => "ta"
-  #     buffer.set_string('---', 1) # write content, starting from offset 1
-  #     # => 3
-  #     buffer
-  #     #  =>
-  #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # 0x00000000  64 2d 2d 2d                                     d---
-  #     string  # original string changed, too
-  #     # => "d---"
+  #       buffer.get_string(2)  # read content starting from offset 2
+  #       # => "ta"
+  #       buffer.set_string('---', 1) # write content, starting from offset 1
+  #       # => 3
+  #       buffer
+  #       # =>
+  #       # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
+  #       # 0x00000000  64 2d 2d 2d                                     d---
+  #       string  # original string changed, too
+  #       # => "d---"
+  #     end
   #
   # Buffer from file:
   #
   #     File.write('test.txt', 'test data')
   #     # => 9
   #     buffer = IO::Buffer.map(File.open('test.txt'))
-  #     #  =>
+  #     # =>
   #     # #<IO::Buffer 0x00007f3f0768c000+9 MAPPED IMMUTABLE>
   #     # ...
   #     buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
@@ -81,7 +81,9 @@ class IO
   #     File.read('test.txt')
   #     # => "t--- data"
   #
-  # **The class is experimental and the interface is subject to change.**
+  # **The class is experimental and the interface is subject to change, this is
+  # especially true of file mappings which may be removed entirely in the
+  # future.**
   #
   class Buffer
     include Comparable
@@ -91,16 +93,18 @@ class IO
     #   - IO::Buffer.for(string) -> readonly io_buffer
     #   - IO::Buffer.for(string) {|io_buffer| ... read/write io_buffer ...}
     # -->
-    # Creates a IO::Buffer from the given string's memory. Without a block a frozen
-    # internal copy of the string is created efficiently and used as the buffer
-    # source. When a block is provided, the buffer is associated directly with the
-    # string's internal data and updating the buffer will update the string.
+    # Creates a zero-copy IO::Buffer from the given string's memory. Without a block
+    # a frozen internal copy of the string is created efficiently and used as the
+    # buffer source. When a block is provided, the buffer is associated directly
+    # with the string's internal buffer and updating the buffer will update the
+    # string.
     #
     # Until #free is invoked on the buffer, either explicitly or via the garbage
     # collector, the source string will be locked and cannot be modified.
     #
     # If the string is frozen, it will create a read-only buffer which cannot be
-    # modified.
+    # modified. If the string is shared, it may trigger a copy-on-write when using
+    # the block form.
     #
     #     string = 'test'
     #     buffer = IO::Buffer.for(string)
@@ -162,7 +166,20 @@ class IO
     #
     def self.map: (File file, ?Integer? size, ?Integer offset, ?Integer flags) -> Buffer
 
-    public
+    # <!--
+    #   rdoc-file=io_buffer.c
+    #   - IO::Buffer.string(length) {|io_buffer| ... read/write io_buffer ...} -> string
+    # -->
+    # Creates a new string of the given length and yields a zero-copy IO::Buffer
+    # instance to the block which uses the string as a source. The block is expected
+    # to write to the buffer and the string will be returned.
+    #
+    #     IO::Buffer.string(4) do |buffer|
+    #       buffer.set_string("Ruby")
+    #     end
+    #     # => "Ruby"
+    #
+    def self.string: (int) { (Buffer) -> void } -> String
 
     # <!--
     #   rdoc-file=io_buffer.c
@@ -179,29 +196,29 @@ class IO
     # -->
     # Fill buffer with `value`, starting with `offset` and going for `length` bytes.
     #
-    #     buffer = IO::Buffer.for('test')
+    #     buffer = IO::Buffer.for('test').dup
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  74 65 73 74         test
     #
     #     buffer.clear
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  00 00 00 00         ....
     #
     #     buf.clear(1) # fill with 1
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 01 01 01         ....
     #
     #     buffer.clear(2, 1, 2) # fill with 2, starting from offset 1, for 2 bytes
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 02 02 01         ....
     #
     #     buffer.clear(2, 1) # fill with 2, starting from offset 1
     #     # =>
-    #     #   <IO::Buffer 0x00007fca40087c38+4 SLICE>
+    #     #   <IO::Buffer 0x00007fca40087c38+4 INTERNAL>
     #     #   0x00000000  01 02 02 02         ....
     #
     def clear: (?Integer value, ?Integer offset, ?Integer length) -> self
@@ -210,29 +227,30 @@ class IO
     #   rdoc-file=io_buffer.c
     #   - copy(source, [offset, [length, [source_offset]]]) -> size
     # -->
-    # Efficiently copy data from a source IO::Buffer into the buffer, at `offset`
-    # using `memcpy`. For copying String instances, see #set_string.
+    # Efficiently copy from a source IO::Buffer into the buffer, at `offset` using
+    # `memmove`. For copying String instances, see #set_string.
     #
     #     buffer = IO::Buffer.new(32)
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000555f5ca22520+32 INTERNAL>
     #     # 0x00000000  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
     #     # 0x00000010  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................  *
     #
     #     buffer.copy(IO::Buffer.for("test"), 8)
-    #     # => 4 -- size of data copied
+    #     # => 4 -- size of buffer copied
     #     buffer
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000555f5cf8fe40+32 INTERNAL>
     #     # 0x00000000  00 00 00 00 00 00 00 00 74 65 73 74 00 00 00 00 ........test....
     #     # 0x00000010  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ *
     #
-    # #copy can be used to put data into strings associated with buffer:
+    # #copy can be used to put buffer into strings associated with buffer:
     #
-    #     string= "data:    "
+    #     string = "data:    "
     #     # => "data:    "
-    #     buffer = IO::Buffer.for(str)
-    #     buffer.copy(IO::Buffer.for("test"), 5)
+    #     buffer = IO::Buffer.for(string) do |buffer|
+    #       buffer.copy(IO::Buffer.for("test"), 5)
+    #     end
     #     # => 4
     #     string
     #     # => "data:test"
@@ -247,38 +265,54 @@ class IO
     # See ::map for details of creation of mutable file mappings, this will work:
     #
     #     buffer = IO::Buffer.map(File.open('test.txt', 'r+'))
-    #     buffer.copy("boom", 0)
+    #     buffer.copy(IO::Buffer.for("boom"), 0)
     #     # => 4
     #     File.read('test.txt')
     #     # => "boom"
     #
-    # Attempt to copy the data which will need place outside of buffer's bounds will
-    # fail:
+    # Attempt to copy the buffer which will need place outside of buffer's bounds
+    # will fail:
     #
     #     buffer = IO::Buffer.new(2)
-    #     buffer.copy('test', 0)
-    #     # in `copy': Specified offset+length exceeds source size! (ArgumentError)
+    #     buffer.copy(IO::Buffer.for('test'), 0)
+    #     # in `copy': Specified offset+length is bigger than the buffer size! (ArgumentError)
+    #
+    # It is safe to copy between memory regions that overlaps each other. In such
+    # case, the data is copied as if the data was first copied from the source
+    # buffer to a temporary buffer, and then copied from the temporary buffer to the
+    # destination buffer.
+    #
+    #     buffer = IO::Buffer.new(10)
+    #     buffer.set_string("0123456789")
+    #     buffer.copy(buffer, 3, 7)
+    #     # => 7
+    #     buffer
+    #     # =>
+    #     # #<IO::Buffer 0x000056494f8ce440+10 INTERNAL>
+    #     # 0x00000000  30 31 32 30 31 32 33 34 35 36                   0120123456
     #
     def copy: (Buffer source, ?Integer offset, ?Integer length, ?Integer source_offset) -> Integer
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - external? -> true or false
+    #   - empty? -> true or false
     # -->
-    # If the buffer is _external_, meaning it references from memory which is not
-    #     allocated or mapped by the buffer itself.
-    #
-    #     A buffer created using ::for has an external reference to the string's
-    #     memory.
-    #
-    # External buffer can't be resized.
+    # If the buffer has 0 size: it is created by ::new with size 0, or with ::for
+    # from an empty string. (Note that empty files can't be mapped, so the buffer
+    # created with ::map will never be empty.)
     #
     def empty?: () -> bool
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - external?()
+    #   - external? -> true or false
     # -->
+    # The buffer is *external* if it references the memory which is not allocated or
+    # mapped by the buffer itself.
+    #
+    # A buffer created using ::for has an external reference to the string's memory.
+    #
+    # External buffer can't be resized.
     #
     def external?: () -> bool
 
@@ -291,9 +325,10 @@ class IO
     # *   for a buffer created from scratch: free memory.
     # *   for a buffer created from string: undo the association.
     #
-    #
     # After the buffer is freed, no further operations can't be performed on it.
     #
+    # You can resize a freed buffer to re-allocate it.
+    #
     #     buffer = IO::Buffer.for('test')
     #     buffer.free
     #     # => #<IO::Buffer 0x0000000000000000+0 NULL>
@@ -307,8 +342,6 @@ class IO
     #     buffer.null?
     #     # => true
     #
-    # You can resize a freed buffer to re-allocate it.
-    #
     def free: () -> self
 
     # <!--
@@ -330,9 +363,9 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - get_value(type, offset) -> numeric
+    #   - get_value(buffer_type, offset) -> numeric
     # -->
-    # Read from buffer a value of `type` at `offset`. `type` should be one of
+    # Read from buffer a value of `type` at `offset`. `buffer_type` should be one of
     # symbols:
     #
     # *   `:U8`: unsigned integer, 1 byte
@@ -354,8 +387,9 @@ class IO
     # *   `:f64`: double, 8 bytes, little-endian
     # *   `:F64`: double, 8 bytes, big-endian
     #
-    #
-    # Example:
+    # A buffer type refers specifically to the type of binary buffer that is stored
+    # in the buffer. For example, a `:u32` buffer type is a 32-bit unsigned integer
+    # in little-endian format.
     #
     #     string = [1.5].pack('f')
     #     # => "\x00\x00\xC0?"
@@ -374,15 +408,35 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - hexdump()
+    #   - hexdump([offset, [length, [width]]]) -> string
     # -->
+    # Returns a human-readable string representation of the buffer. The exact format
+    # is subject to change.
+    #
+    #     buffer = IO::Buffer.for("Hello World")
+    #     puts buffer.hexdump
+    #     # 0x00000000  48 65 6c 6c 6f 20 57 6f 72 6c 64                Hello World
+    #
+    # As buffers are usually fairly big, you may want to limit the output by
+    # specifying the offset and length:
+    #
+    #     puts buffer.hexdump(6, 5)
+    #     # 0x00000006  57 6f 72 6c 64                                  World
     #
     def hexdump: () -> String
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - inspect()
+    #   - inspect -> string
     # -->
+    # Inspect the buffer and report useful information about it's internal state.
+    # Only a limited portion of the buffer will be displayed in a hexdump style
+    # format.
+    #
+    #     buffer = IO::Buffer.for("Hello World")
+    #     puts buffer.inspect
+    #     # #<IO::Buffer 0x000000010198ccd8+11 EXTERNAL READONLY SLICE>
+    #     # 0x00000000  48 65 6c 6c 6f 20 57 6f 72 6c 64                Hello World
     #
     def inspect: () -> String
 
@@ -413,6 +467,12 @@ class IO
     # block is performed, the buffer is considered locked, and no other code can
     # enter the lock. Also, locked buffer can't be changed with #resize or #free.
     #
+    # The following operations acquire a lock: #resize, #free.
+    #
+    # Locking is not thread safe. It is designed as a safety net around non-blocking
+    # system calls. You can only share a buffer between threads with appropriate
+    # synchronisation techniques.
+    #
     #     buffer = IO::Buffer.new(4)
     #     buffer.locked? #=> false
     #
@@ -425,16 +485,10 @@ class IO
     #     Fiber.schedule do
     #       # in `locked': Buffer already locked! (IO::Buffer::LockedError)
     #       buffer.locked do
-    #         buffer.set_string(...)
+    #         buffer.set_string("test", 0)
     #       end
     #     end
     #
-    # The following operations acquire a lock: #resize, #free.
-    #
-    # Locking is not thread safe. It is designed as a safety net around non-blocking
-    # system calls. You can only share a buffer between threads with appropriate
-    # synchronisation techniques.
-    #
     def locked: [A] () { (IO::Buffer) -> A } -> A
 
     # <!--
@@ -473,35 +527,116 @@ class IO
     #   rdoc-file=io_buffer.c
     #   - null? -> true or false
     # -->
-    # If the buffer was freed with #free or was never allocated in the first place.
+    # If the buffer was freed with #free, transferred with #transfer, or was never
+    # allocated in the first place.
+    #
+    #     buffer = IO::Buffer.new(0)
+    #     buffer.null? #=> true
+    #
+    #     buffer = IO::Buffer.new(4)
+    #     buffer.null? #=> false
+    #     buffer.free
+    #     buffer.null? #=> true
     #
     def null?: () -> bool
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - pread(p1, p2, p3)
+    #   - pread(io, from, [length, [offset]]) -> read length or -errno
     # -->
+    # Read at least `length` bytes from the `io` starting at the specified `from`
+    # position, into the buffer starting at `offset`. If an error occurs, return
+    # `-errno`.
+    #
+    # If `length` is not given or `nil`, it defaults to the size of the buffer minus
+    # the offset, i.e. the entire buffer.
+    #
+    # If `length` is zero, exactly one `pread` operation will occur.
+    #
+    # If `offset` is not given, it defaults to zero, i.e. the beginning of the
+    # buffer.
+    #
+    #     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
     #
     def pread: (untyped, untyped, untyped) -> untyped
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - pwrite(p1, p2, p3)
+    #   - pwrite(io, from, [length, [offset]]) -> written length or -errno
     # -->
+    # Write at least `length` bytes from the buffer starting at `offset`, into the
+    # `io` starting at the specified `from` position. If an error occurs, return
+    # `-errno`.
+    #
+    # If `length` is not given or `nil`, it defaults to the size of the buffer minus
+    # the offset, i.e. the entire buffer.
+    #
+    # If `length` is zero, exactly one `pwrite` operation will occur.
+    #
+    # If `offset` is not given, it defaults to zero, i.e. the beginning of the
+    # buffer.
+    #
+    # If the `from` position 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
+    # `output.txt`, starting from file position 2.
     #
     def pwrite: (untyped, untyped, untyped) -> untyped
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - read(p1, p2)
+    #   - read(io, [length, [offset]]) -> read length or -errno
     # -->
+    # Read at least `length` bytes from the `io`, into the buffer starting at
+    # `offset`. If an error occurs, return `-errno`.
+    #
+    # If `length` is not given or `nil`, it defaults to the size of the buffer minus
+    # the offset, i.e. the entire buffer.
+    #
+    # If `length` is zero, exactly one `read` operation will occur.
+    #
+    # If `offset` is not given, it defaults to zero, i.e. the beginning of the
+    # buffer.
+    #
+    #     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
     #
     def read: (untyped, untyped) -> untyped
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - readonly?()
+    #   - readonly? -> true or false
     # -->
+    # If the buffer is *read only*, meaning the buffer cannot be modified using
+    # #set_value, #set_string or #copy and similar.
+    #
+    # Frozen strings and read-only files create read-only buffers.
     #
     def readonly?: () -> bool
 
@@ -516,7 +651,7 @@ class IO
     #     buffer = IO::Buffer.new(4)
     #     buffer.set_string("test", 0)
     #     buffer.resize(8) # resize to 8 bytes
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000555f5d1a1630+8 INTERNAL>
     #     # 0x00000000  74 65 73 74 00 00 00 00                         test....
     #
@@ -526,8 +661,27 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - set_string(*args)
+    #   - set_string(string, [offset, [length, [source_offset]]]) -> size
     # -->
+    # Efficiently copy from a source String into the buffer, at `offset` using
+    # `memmove`.
+    #
+    #     buf = IO::Buffer.new(8)
+    #     # =>
+    #     # #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
+    #     # 0x00000000  00 00 00 00 00 00 00 00                         ........
+    #
+    #     # set buffer starting from offset 1, take 2 bytes starting from string's
+    #     # second
+    #     buf.set_string('test', 1, 2, 1)
+    #     # => 2
+    #     buf
+    #     # =>
+    #     # #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
+    #     # 0x00000000  00 65 73 00 00 00 00 00                         .es.....
+    #
+    # See also #copy for examples of how buffer writing might be used for changing
+    # associated strings and files.
     #
     def set_string: (*untyped) -> untyped
 
@@ -539,13 +693,15 @@ class IO
     # symbols described in #get_value.
     #
     #     buffer = IO::Buffer.new(8)
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
     #     # 0x00000000  00 00 00 00 00 00 00 00
+    #
     #     buffer.set_value(:U8, 1, 111)
     #     # => 1
+    #
     #     buffer
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
     #     # 0x00000000  00 6f 00 00 00 00 00 00                         .o......
     #
@@ -554,11 +710,12 @@ class IO
     #
     #     buffer = IO::Buffer.new(8)
     #     buffer.set_value(:U32, 0, 2.5)
+    #
     #     buffer
-    #     #   =>
-    #     #  #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
-    #     #  0x00000000  00 00 00 02 00 00 00 00
-    #     #                       ^^ the same as if we'd pass just integer 2
+    #     # =>
+    #     # #<IO::Buffer 0x0000555f5c9a2d50+8 INTERNAL>
+    #     # 0x00000000  00 00 00 02 00 00 00 00
+    #     #                      ^^ the same as if we'd pass just integer 2
     #
     def set_value: (int_get_type | float_get_type, Integer offset, Float | Integer value) -> Integer
 
@@ -573,7 +730,7 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - slice(offset, length) -> io_buffer
+    #   - slice([offset, [length]]) -> io_buffer
     # -->
     # Produce another IO::Buffer which is a slice (or view into) the current one
     # starting at `offset` bytes and going for `length` bytes.
@@ -581,33 +738,46 @@ class IO
     # The slicing happens without copying of memory, and the slice keeps being
     # associated with the original buffer's source (string, or file), if any.
     #
-    # Raises RuntimeError if the <tt>offset+length<tt> is out of the current
-    # buffer's bounds.
+    # If the offset is not given, it will be zero. If the offset is negative, it
+    # will raise an ArgumentError.
+    #
+    # If the length is not given, the slice will be as long as the original buffer
+    # minus the specified offset. If the length is negative, it will raise an
+    # ArgumentError.
+    #
+    # Raises RuntimeError if the `offset+length` is out of the current buffer's
+    # bounds.
     #
     #     string = 'test'
-    #     buffer = IO::Buffer.for(string)
+    #     buffer = IO::Buffer.for(string).dup
+    #
+    #     slice = buffer.slice
+    #     # =>
+    #     # #<IO::Buffer 0x0000000108338e68+4 SLICE>
+    #     # 0x00000000  74 65 73 74                                     test
+    #
+    #     buffer.slice(2)
+    #     # =>
+    #     # #<IO::Buffer 0x0000000108338e6a+2 SLICE>
+    #     # 0x00000000  73 74                                           st
     #
     #     slice = buffer.slice(1, 2)
     #     # =>
-    #     #  #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
-    #     #  0x00000000  65 73                                           es
+    #     # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
+    #     # 0x00000000  65 73                                           es
     #
     #     # Put "o" into 0s position of the slice
     #     slice.set_string('o', 0)
     #     slice
     #     # =>
-    #     #  #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
-    #     #  0x00000000  6f 73                                           os
+    #     # #<IO::Buffer 0x00007fc3d34ebc49+2 SLICE>
+    #     # 0x00000000  6f 73                                           os
     #
     #     # it is also visible at position 1 of the original buffer
     #     buffer
     #     # =>
-    #     #  #<IO::Buffer 0x00007fc3d31e2d80+4 SLICE>
-    #     #  0x00000000  74 6f 73 74                                     tost
-    #
-    #     # ...and original string
-    #     string
-    #     # => tost
+    #     # #<IO::Buffer 0x00007fc3d31e2d80+4 INTERNAL>
+    #     # 0x00000000  74 6f 73 74                                     tost
     #
     def slice: (Integer offset, Integer length) -> Buffer
 
@@ -627,16 +797,17 @@ class IO
     #   rdoc-file=io_buffer.c
     #   - transfer -> new_io_buffer
     # -->
-    # Transfers ownership to a new buffer, deallocating the current one.
+    # Transfers ownership of the underlying memory to a new buffer, causing the
+    # current buffer to become uninitialized.
     #
     #     buffer = IO::Buffer.new('test')
     #     other = buffer.transfer
     #     other
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x00007f136a15f7b0+4 SLICE>
     #     # 0x00000000  74 65 73 74                                     test
     #     buffer
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x0000000000000000+0 NULL>
     #     buffer.null?
     #     # => true
@@ -647,17 +818,32 @@ class IO
     #   rdoc-file=io_buffer.c
     #   - valid? -> true or false
     # -->
-    # Returns whether the buffer data is accessible.
+    # Returns whether the buffer buffer is accessible.
     #
-    # A buffer becomes invalid if it is a slice of another buffer which has been
-    # freed.
+    # A buffer becomes invalid if it is a slice of another buffer (or string) which
+    # has been freed or re-allocated at a different address.
     #
     def valid?: () -> bool
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - write(p1, p2)
+    #   - write(io, [length, [offset]]) -> written length or -errno
     # -->
+    # Write at least `length` bytes from the buffer starting at `offset`, into the
+    # `io`. If an error occurs, return `-errno`.
+    #
+    # If `length` is not given or `nil`, it defaults to the size of the buffer minus
+    # the offset, i.e. the entire buffer.
+    #
+    # If `length` is zero, exactly one `write` operation will occur.
+    #
+    # If `offset` is not given, it defaults to zero, i.e. 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 `output.txt`
     #
     def write: (untyped, untyped) -> untyped
 
@@ -669,64 +855,129 @@ class IO
     # -->
     # Create a new zero-filled IO::Buffer of `size` bytes. By default, the buffer
     # will be *internal*: directly allocated chunk of the memory. But if the
-    # requested `size` is more than OS-specific IO::Bufer::PAGE_SIZE, the buffer
+    # requested `size` is more than OS-specific IO::Buffer::PAGE_SIZE, the buffer
     # would be allocated using the virtual memory mechanism (anonymous `mmap` on
     # Unix, `VirtualAlloc` on Windows). The behavior can be forced by passing
     # IO::Buffer::MAPPED as a second parameter.
     #
-    # Examples
-    #
     #     buffer = IO::Buffer.new(4)
     #     # =>
-    #     #  #<IO::Buffer 0x000055b34497ea10+4 INTERNAL>
-    #     #  0x00000000  00 00 00 00                                     ....
+    #     # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL>
+    #     # 0x00000000  00 00 00 00                                     ....
     #
     #     buffer.get_string(0, 1) # => "\x00"
     #
     #     buffer.set_string("test")
     #     buffer
-    #     #  =>
+    #     # =>
     #     # #<IO::Buffer 0x000055b34497ea10+4 INTERNAL>
     #     # 0x00000000  74 65 73 74                                     test
     #
     def initialize: (?Integer size, ?Integer flags) -> void
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Refers to big endian byte order, where the most significant byte is stored
+    # first. See #get_value for more details.
+    #
     BIG_ENDIAN: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # The default buffer size, typically a (small) multiple of the PAGE_SIZE. Can be
+    # explicitly specified by setting the RUBY_IO_BUFFER_DEFAULT_SIZE environment
+    # variable.
+    #
     DEFAULT_SIZE: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is owned by someone else. See
+    # #external? for more details.
+    #
     EXTERNAL: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Refers to the byte order of the host machine. See #get_value for more details.
+    #
     HOST_ENDIAN: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is owned by the buffer. See #internal?
+    # for more details.
+    #
     INTERNAL: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Refers to little endian byte order, where the least significant byte is stored
+    # first. See #get_value for more details.
+    #
     LITTLE_ENDIAN: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is locked and cannot be resized or
+    # freed. See #locked? and #locked for more details.
+    #
     LOCKED: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is mapped by the operating system. See
+    # #mapped? for more details.
+    #
     MAPPED: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Refers to network byte order, which is the same as big endian. See #get_value
+    # for more details.
+    #
     NETWORK_ENDIAN: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # The operating system page size. Used for efficient page-aligned memory
+    # allocations.
+    #
     PAGE_SIZE: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is mapped privately and changes won't
+    # be replicated to the underlying file. See #private? for more details.
+    #
     PRIVATE: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Indicates that the memory in the buffer is read only, and attempts to modify
+    # it will fail. See #readonly? for more details.
+    #
     READONLY: Integer
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Raised when an operation would resize or re-allocate a locked buffer.
+    #
     class LockedError < RuntimeError
     end
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Raised when the buffer cannot be allocated for some reason, or you try to use
+    # a buffer that's not allocated.
+    #
     class AllocationError < RuntimeError
     end
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Raised when you try to write to a read-only buffer, or resize an external
+    # buffer.
+    #
     class AccessError < RuntimeError
     end
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Raised if you try to access a buffer slice which no longer references a valid
+    # memory range of the underlying source.
+    #
     class InvalidatedError < RuntimeError
     end
 
+    # <!-- rdoc-file=io_buffer.c -->
+    # Raised if the mask given to a binary operation is invalid, e.g. zero length or
+    # overlaps the target buffer.
+    #
     class MaskError < ArgumentError
     end
   end