rbs 3.3.2 → 3.4.0.pre.1

data/core/integer.rbs

@@ -131,7 +131,7 @@ class Integer < Numeric
   def self.sqrt: (int n) -> Integer
 
   # <!--
-  #   rdoc-file=numeric.rb
+  #   rdoc-file=numeric.c
   #   - Integer.try_convert(object) -> object, integer, or nil
   # -->
   # If `object` is an Integer object, returns `object`.
@@ -178,8 +178,6 @@ class Integer < Numeric
   #     10 % 3.0            # => 1.0
   #     10 % Rational(3, 1) # => (1/1)
   #
-  # Integer#modulo is an alias for Integer#%.
-  #
   def %: (Float) -> Float
        | (Rational) -> Rational
        | (Integer) -> Integer
@@ -277,9 +275,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -int  ->  integer
+  #   - -int -> integer
   # -->
-  # Returns `int`, negated.
+  # Returns `self`, negated.
   #
   def -@: () -> Integer
 
@@ -391,8 +389,6 @@ class Integer < Numeric
   #
   # Related: Integer#eql? (requires `other` to be an Integer).
   #
-  # Integer#=== is an alias for Integer#==.
-  #
   def ==: (untyped) -> bool
 
   # <!--
@@ -406,8 +402,6 @@ class Integer < Numeric
   #
   # Related: Integer#eql? (requires `other` to be an Integer).
   #
-  # Integer#=== is an alias for Integer#==.
-  #
   def ===: (untyped) -> bool
 
   # <!--
@@ -519,16 +513,13 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.abs        ->  integer
-  #   - int.magnitude  ->  integer
+  #   - abs -> integer
   # -->
-  # Returns the absolute value of `int`.
+  # Returns the absolute value of `self`.
   #
-  #     (-12345).abs   #=> 12345
-  #     -12345.abs     #=> 12345
-  #     12345.abs      #=> 12345
-  #
-  # Integer#magnitude is an alias for Integer#abs.
+  #     (-12345).abs # => 12345
+  #     -12345.abs   # => 12345
+  #     12345.abs    # => 12345
   #
   def abs: () -> Integer
 
@@ -586,44 +577,43 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.bit_length  ->  integer
+  #   - bit_length -> integer
   # -->
-  # Returns the number of bits of the value of `int`.
-  #
-  # "Number of bits" means the bit position of the highest bit which is different
-  # from the sign bit (where the least significant bit has bit position 1). If
-  # there is no such bit (zero or minus one), zero is returned.
-  #
-  # I.e. this method returns *ceil(log2(int < 0 ? -int : int+1))*.
-  #
-  #     (-2**1000-1).bit_length   #=> 1001
-  #     (-2**1000).bit_length     #=> 1000
-  #     (-2**1000+1).bit_length   #=> 1000
-  #     (-2**12-1).bit_length     #=> 13
-  #     (-2**12).bit_length       #=> 12
-  #     (-2**12+1).bit_length     #=> 12
-  #     -0x101.bit_length         #=> 9
-  #     -0x100.bit_length         #=> 8
-  #     -0xff.bit_length          #=> 8
-  #     -2.bit_length             #=> 1
-  #     -1.bit_length             #=> 0
-  #     0.bit_length              #=> 0
-  #     1.bit_length              #=> 1
-  #     0xff.bit_length           #=> 8
-  #     0x100.bit_length          #=> 9
-  #     (2**12-1).bit_length      #=> 12
-  #     (2**12).bit_length        #=> 13
-  #     (2**12+1).bit_length      #=> 13
-  #     (2**1000-1).bit_length    #=> 1000
-  #     (2**1000).bit_length      #=> 1001
-  #     (2**1000+1).bit_length    #=> 1001
-  #
-  # This method can be used to detect overflow in Array#pack as follows:
+  # Returns the number of bits of the value of `self`, which is the bit position
+  # of the highest-order bit that is different from the sign bit (where the least
+  # significant bit has bit position 1). If there is no such bit (zero or minus
+  # one), returns zero.
+  #
+  # This method returns `ceil(log2(self < 0 ? -self : self + 1))`>.
+  #
+  #     (-2**1000-1).bit_length   # => 1001
+  #     (-2**1000).bit_length     # => 1000
+  #     (-2**1000+1).bit_length   # => 1000
+  #     (-2**12-1).bit_length     # => 13
+  #     (-2**12).bit_length       # => 12
+  #     (-2**12+1).bit_length     # => 12
+  #     -0x101.bit_length         # => 9
+  #     -0x100.bit_length         # => 8
+  #     -0xff.bit_length          # => 8
+  #     -2.bit_length             # => 1
+  #     -1.bit_length             # => 0
+  #     0.bit_length              # => 0
+  #     1.bit_length              # => 1
+  #     0xff.bit_length           # => 8
+  #     0x100.bit_length          # => 9
+  #     (2**12-1).bit_length      # => 12
+  #     (2**12).bit_length        # => 13
+  #     (2**12+1).bit_length      # => 13
+  #     (2**1000-1).bit_length    # => 1000
+  #     (2**1000).bit_length      # => 1001
+  #     (2**1000+1).bit_length    # => 1001
+  #
+  # For Integer *n*, this method can be used to detect overflow in Array#pack:
   #
   #     if n.bit_length < 32
-  #       [n].pack("l") # no overflow
+  #       [n].pack('l') # No overflow.
   #     else
-  #       raise "overflow"
+  #       raise 'Overflow'
   #     end
   #
   def bit_length: () -> Integer
@@ -655,16 +645,16 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - ceildiv(other) -> integer
+  #   - ceildiv(numeric) -> integer
   # -->
-  # Returns the result of division `self` by `other`. The result is rounded up to
-  # the nearest integer.
+  # Returns the result of division `self` by `numeric`. rounded up to the nearest
+  # integer.
   #
-  #     3.ceildiv(3) # => 1
-  #     4.ceildiv(3) # => 2
+  #     3.ceildiv(3)   # => 1
+  #     4.ceildiv(3)   # => 2
   #
-  #     4.ceildiv(-3) # => -1
-  #     -4.ceildiv(3) # => -1
+  #     4.ceildiv(-3)  # => -1
+  #     -4.ceildiv(3)  # => -1
   #     -4.ceildiv(-3) # => 2
   #
   #     3.ceildiv(1.2) # => 3
@@ -712,9 +702,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.denominator  ->  1
+  #   - denominator -> 1
   # -->
-  # Returns 1.
+  # Returns `1`.
   #
   def denominator: () -> Integer
 
@@ -806,9 +796,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.even?  ->  true or false
+  #   - even? -> true or false
   # -->
-  # Returns `true` if `int` is an even number.
+  # Returns `true` if `self` is an even number, `false` otherwise.
   #
   def even?: () -> bool
 
@@ -904,15 +894,13 @@ class Integer < Numeric
   #
   # Raises an exception if `base` is out of range.
   #
-  # Integer#inspect is an alias for Integer#to_s.
-  #
   alias inspect to_s
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.integer?  ->  true
+  #   - integer? -> true
   # -->
-  # Since `int` is already an Integer, this always returns `true`.
+  # Since `self` is already an Integer, always returns `true`.
   #
   def integer?: () -> true
 
@@ -961,8 +949,6 @@ class Integer < Numeric
   #     10 % 3.0            # => 1.0
   #     10 % Rational(3, 1) # => (1/1)
   #
-  # Integer#modulo is an alias for Integer#%.
-  #
   alias modulo %
 
   def negative?: () -> bool
@@ -973,8 +959,6 @@ class Integer < Numeric
   #     1.succ  #=> 2
   #     -1.succ #=> 0
   #
-  # Integer#next is an alias for Integer#succ.
-  #
   # Related: Integer#pred (predecessor value).
   #
   def next: () -> Integer
@@ -1006,31 +990,25 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.numerator  ->  self
+  #   - numerator -> self
   # -->
-  # Returns self.
+  # Returns `self`.
   #
   def numerator: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.odd?  ->  true or false
+  #   - odd? -> true or false
   # -->
-  # Returns `true` if `int` is an odd number.
+  # Returns `true` if `self` is an odd number, `false` otherwise.
   #
   def odd?: () -> bool
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.ord  ->  self
+  #   - ord -> self
   # -->
-  # Returns the `int` itself.
-  #
-  #     97.ord   #=> 97
-  #
-  # This method is intended for compatibility to character literals in Ruby 1.9.
-  #
-  # For example, `?a.ord` returns 97 both in 1.8 and 1.9.
+  # Returns `self`; intended for compatibility to character literals in Ruby 1.9.
   #
   def ord: () -> Integer
 
@@ -1168,19 +1146,17 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.size  ->  int
+  #   - size -> integer
   # -->
-  # Document-method: Integer#size
+  # Returns the number of bytes in the machine representation of `self`; the value
+  # is system-dependent:
   #
-  # Returns the number of bytes in the machine representation of `int` (machine
-  # dependent).
-  #
-  #     1.size               #=> 8
-  #     -1.size              #=> 8
-  #     2147483647.size      #=> 8
-  #     (256**10 - 1).size   #=> 10
-  #     (256**20 - 1).size   #=> 20
-  #     (256**40 - 1).size   #=> 40
+  #     1.size             # => 8
+  #     -1.size            # => 8
+  #     2147483647.size    # => 8
+  #     (256**10 - 1).size # => 10
+  #     (256**20 - 1).size # => 20
+  #     (256**40 - 1).size # => 40
   #
   def size: () -> Integer
 
@@ -1204,14 +1180,12 @@ class Integer < Numeric
   #     1.succ  #=> 2
   #     -1.succ #=> 0
   #
-  # Integer#next is an alias for Integer#succ.
-  #
   # Related: Integer#pred (predecessor value).
   #
   def succ: () -> Integer
 
   # <!--
-  #   rdoc-file=numeric.c
+  #   rdoc-file=numeric.rb
   #   - times {|i| ... } -> self
   #   - times            -> enumerator
   # -->
@@ -1246,19 +1220,17 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.to_i    ->  integer
+  #   - to_i -> self
   # -->
-  # Since `int` is already an Integer, returns `self`.
-  #
-  # #to_int is an alias for #to_i.
+  # Returns `self` (which is already an Integer).
   #
   def to_i: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.to_int  ->  integer
+  #   - to_int -> self
   # -->
-  # Since `int` is already an Integer, returns `self`.
+  # Returns `self` (which is already an Integer).
   #
   alias to_int to_i
 
@@ -1290,8 +1262,6 @@ class Integer < Numeric
   #
   # Raises an exception if `base` is out of range.
   #
-  # Integer#inspect is an alias for Integer#to_s.
-  #
   def to_s: () -> String
           | (2) -> String
           | (3) -> String
@@ -1377,9 +1347,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.zero? -> true or false
+  #   - zero? -> true or false
   # -->
-  # Returns `true` if `int` has a zero value.
+  # Returns `true` if `self` has a zero value, `false` otherwise.
   #
   def zero?: () -> bool
 
@@ -1400,16 +1370,15 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - ~int  ->  integer
+  #   - ~int -> integer
   # -->
-  # One's complement: returns a number where each bit is flipped.
+  # One's complement: returns the value of `self` with each bit inverted.
   #
-  # Inverts the bits in an Integer. As integers are conceptually of infinite
-  # length, the result acts as if it had an infinite number of one bits to the
-  # left. In hex representations, this is displayed as two periods to the left of
-  # the digits.
+  # Because an integer value is conceptually of infinite length, the result acts
+  # as if it had an infinite number of one bits to the left. In hex
+  # representations, this is displayed as two periods to the left of the digits:
   #
-  #     sprintf("%X", ~0x1122334455)    #=> "..FEEDDCCBBAA"
+  #     sprintf("%X", ~0x1122334455)    # => "..FEEDDCCBBAA"
   #
   def ~: () -> Integer
 end

data/core/io/buffer.rbs

@@ -4,8 +4,8 @@ class IO
   # IO::Buffer is a low-level efficient buffer for input/output. There are three
   # ways of using buffer:
   #
-  # *   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;
   # *   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);
@@ -39,7 +39,7 @@ class IO
   #
   # Buffer from string:
   #
-  #     string = 'data'
+  #     string = 'buffer'
   #     buffer = IO::Buffer.for(string)
   #     # =>
   #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
@@ -47,7 +47,7 @@ class IO
   #     buffer
   #     # =>
   #     # #<IO::Buffer 0x00007f3f02be9b18+4 SLICE>
-  #     # 0x00000000  64 61 74 61                                     data
+  #     # 0x00000000  64 61 74 61                                     buffer
   #
   #     buffer.get_string(2)  # read content starting from offset 2
   #     # => "ta"
@@ -62,7 +62,7 @@ class IO
   #
   # Buffer from file:
   #
-  #     File.write('test.txt', 'test data')
+  #     File.write('test.txt', 'test buffer')
   #     # => 9
   #     buffer = IO::Buffer.map(File.open('test.txt'))
   #     # =>
@@ -79,7 +79,7 @@ class IO
   #     buffer.set_string('---', 1)
   #     # => 3 -- bytes written
   #     File.read('test.txt')
-  #     # => "t--- data"
+  #     # => "t--- buffer"
   #
   # **The class is experimental and the interface is subject to change.**
   #
@@ -94,13 +94,14 @@ class IO
     # 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.
+    # 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)
@@ -164,6 +165,21 @@ class IO
     #
     def self.map: (File file, ?Integer? size, ?Integer offset, ?Integer flags) -> Buffer
 
+    # <!--
+    #   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 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
+
     public
 
     # <!--
@@ -212,8 +228,8 @@ 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
+    # `memcpy`. For copying String instances, see #set_string.
     #
     #     buffer = IO::Buffer.new(32)
     #     # =>
@@ -222,22 +238,22 @@ class IO
     #     # 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:    "
-    #     # => "data:    "
+    #     string= "buffer:    "
+    #     # => "buffer:    "
     #     buffer = IO::Buffer.for(string)
     #     buffer.copy(IO::Buffer.for("test"), 5)
     #     # => 4
     #     string
-    #     # => "data:test"
+    #     # => "buffer:test"
     #
     # Attempt to copy into a read-only buffer will fail:
     #
@@ -254,12 +270,12 @@ class IO
     #     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(IO::Buffer.for('test'), 0)
-    #     # in `copy': Specified offset+length exceeds source size! (ArgumentError)
+    #     # in `copy': Specified offset+length is bigger than the buffer size! (ArgumentError)
     #
     def copy: (Buffer source, ?Integer offset, ?Integer length, ?Integer source_offset) -> Integer
 
@@ -336,9 +352,9 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - get_value(data_type, offset) -> numeric
+    #   - get_value(buffer_type, offset) -> numeric
     # -->
-    # Read from buffer a value of `type` at `offset`. `data_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
@@ -361,9 +377,9 @@ class IO
     # *   `:F64`: double, 8 bytes, big-endian
     #
     #
-    # A data type refers specifically to the type of binary data that is stored in
-    # the buffer. For example, a `:u32` data type is a 32-bit unsigned integer in
-    # little-endian format.
+    # 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.
     #
     # Example:
     #
@@ -493,13 +509,19 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - pread(io, from, length, [offset]) -> read length or -errno
+    #   - 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
+    # 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 `offset` is not given, put it at the beginning of the buffer.
+    # 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.
     #
     # Example:
     #
@@ -522,14 +544,24 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - pwrite(io, from, length, [offset]) -> written length or -errno
+    #   - 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 `-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 `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.
+    # 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.
+    #
+    # Example:
     #
     #     out = File.open('output.txt', File::RDWR) # open for read/write, no truncation
     #     IO::Buffer.for('1234567').pwrite(out, 2, 3, 1)
@@ -541,14 +573,18 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - read(io, length, [offset]) -> read length or -errno
+    #   - read(io, [length, [offset]]) -> read length or -errno
     # -->
-    # Read at most `length` bytes from `io` into the buffer, starting at `offset`.
-    # If an error occurs, return `-errno`.
+    # Read at least `length` bytes from the `io`, into the buffer starting at
+    # `offset`. If an error occurs, return `-errno`.
     #
-    # If `offset` is not given, read from the beginning of the buffer.
+    # 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 0, read nothing.
+    # 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.
     #
     # Example:
     #
@@ -600,15 +636,15 @@ class IO
     #   rdoc-file=io_buffer.c
     #   - set_string(string, [offset, [length, [source_offset]]]) -> size
     # -->
-    # Efficiently copy data from a source String into the buffer, at `offset` using
-    # `memcpy`.
+    # Efficiently copy buffer from a source String into the buffer, at `offset`
+    # using `memcpy`.
     #
     #     buf = IO::Buffer.new(8)
     #     # =>
     #     # #<IO::Buffer 0x0000557412714a20+8 INTERNAL>
     #     # 0x00000000  00 00 00 00 00 00 00 00                         ........
     #
-    #     # set data starting from offset 1, take 2 bytes starting from string's
+    #     # set buffer starting from offset 1, take 2 bytes starting from string's
     #     # second
     #     buf.set_string('test', 1, 2, 1)
     #     # => 2
@@ -667,7 +703,7 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - slice([offset = 0, [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.
@@ -762,7 +798,7 @@ 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.
@@ -771,14 +807,21 @@ class IO
 
     # <!--
     #   rdoc-file=io_buffer.c
-    #   - write(io, length, [offset]) -> written length or -errno
+    #   - 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 `-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, the bytes are taken from the beginning of the
+    # If `offset` is not given, it defaults to zero, i.e. the beginning of the
     # buffer.
     #
+    # Example:
+    #
     #     out = File.open('output.txt', 'wb')
     #     IO::Buffer.for('1234567').write(out, 3)
     #