rbs 4.0.0.dev.4 → 4.0.0

data/core/io/buffer.rbs

@@ -64,9 +64,9 @@ class IO
   #
   #     File.write('test.txt', 'test data')
   #     # => 9
-  #     buffer = IO::Buffer.map(File.open('test.txt'))
+  #     buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
   #     # =>
-  #     # #<IO::Buffer 0x00007f3f0768c000+9 MAPPED IMMUTABLE>
+  #     # #<IO::Buffer 0x00007f3f0768c000+9 EXTERNAL MAPPED FILE SHARED READONLY>
   #     # ...
   #     buffer.get_string(5, 2) # read 2 bytes, starting from offset 5
   #     # => "da"
@@ -81,9 +81,9 @@ class IO
   #     File.read('test.txt')
   #     # => "t--- data"
   #
-  # **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.**
+  # <strong>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.</strong>
   #
   class Buffer
     include Comparable
@@ -113,7 +113,7 @@ class IO
     #     buffer.get_string(0, 1)
     #     # => "t"
     #     string
-    #     # => "best"
+    #     # => "test"
     #
     #     buffer.resize(100)
     #     # in `resize': Cannot resize external buffer! (IO::Buffer::AccessError)
@@ -131,18 +131,25 @@ class IO
     #   - IO::Buffer.map(file, [size, [offset, [flags]]]) -> io_buffer
     # -->
     # Create an IO::Buffer for reading from `file` by memory-mapping the file.
-    # `file_io` should be a `File` instance, opened for reading.
+    # `file` should be a `File` instance, opened for reading or reading and writing.
+    #
+    # Optional `size` and `offset` of mapping can be specified. Trying to map an
+    # empty file or specify `size` of 0 will raise an error. Valid values for
+    # `offset` are system-dependent.
     #
-    # Optional `size` and `offset` of mapping can be specified.
+    # By default, the buffer is writable and expects the file to be writable. It is
+    # also shared, so several processes can use the same mapping.
     #
-    # By default, the buffer would be immutable (read only); to create a writable
-    # mapping, you need to open a file in read-write mode, and explicitly pass
-    # `flags` argument without IO::Buffer::IMMUTABLE.
+    # You can pass IO::Buffer::READONLY in `flags` argument to make a read-only
+    # buffer; this allows to work with files opened only for reading. Specifying
+    # IO::Buffer::PRIVATE in `flags` creates a private mapping, which will not
+    # impact other processes or the underlying file. It also allows updating a
+    # buffer created from a read-only file.
     #
     #     File.write('test.txt', 'test')
     #
     #     buffer = IO::Buffer.map(File.open('test.txt'), nil, 0, IO::Buffer::READONLY)
-    #     # => #<IO::Buffer 0x00000001014a0000+4 MAPPED READONLY>
+    #     # => #<IO::Buffer 0x00000001014a0000+4 EXTERNAL MAPPED FILE SHARED READONLY>
     #
     #     buffer.readonly?   # => true
     #
@@ -150,7 +157,7 @@ class IO
     #     # => "test"
     #
     #     buffer.set_string('b', 0)
-    #     # `set_string': Buffer is not writable! (IO::Buffer::AccessError)
+    #     # 'IO::Buffer#set_string': Buffer is not writable! (IO::Buffer::AccessError)
     #
     #     # create read/write mapping: length 4 bytes, offset 0, flags 0
     #     buffer = IO::Buffer.map(File.open('test.txt', 'r+'), 4, 0)
@@ -349,7 +356,7 @@ class IO
     #   - get_string([offset, [length, [encoding]]]) -> string
     # -->
     # Read a chunk or all of the buffer into a string, in the specified `encoding`.
-    # If no encoding is provided `Encoding::BINARY` is used.
+    # If no encoding is provided <code>Encoding::BINARY</code> is used.
     #
     #     buffer = IO::Buffer.for('test')
     #     buffer.get_string
@@ -368,28 +375,32 @@ class IO
     # Read from buffer a value of `type` at `offset`. `buffer_type` should be one of
     # symbols:
     #
-    # *   `:U8`: unsigned integer, 1 byte
-    # *   `:S8`: signed integer, 1 byte
-    # *   `:u16`: unsigned integer, 2 bytes, little-endian
-    # *   `:U16`: unsigned integer, 2 bytes, big-endian
-    # *   `:s16`: signed integer, 2 bytes, little-endian
-    # *   `:S16`: signed integer, 2 bytes, big-endian
-    # *   `:u32`: unsigned integer, 4 bytes, little-endian
-    # *   `:U32`: unsigned integer, 4 bytes, big-endian
-    # *   `:s32`: signed integer, 4 bytes, little-endian
-    # *   `:S32`: signed integer, 4 bytes, big-endian
-    # *   `:u64`: unsigned integer, 8 bytes, little-endian
-    # *   `:U64`: unsigned integer, 8 bytes, big-endian
-    # *   `:s64`: signed integer, 8 bytes, little-endian
-    # *   `:S64`: signed integer, 8 bytes, big-endian
-    # *   `:f32`: float, 4 bytes, little-endian
-    # *   `:F32`: float, 4 bytes, big-endian
-    # *   `:f64`: double, 8 bytes, little-endian
-    # *   `:F64`: double, 8 bytes, big-endian
+    # *   <code>:U8</code>: unsigned integer, 1 byte
+    # *   <code>:S8</code>: signed integer, 1 byte
+    # *   <code>:u16</code>: unsigned integer, 2 bytes, little-endian
+    # *   <code>:U16</code>: unsigned integer, 2 bytes, big-endian
+    # *   <code>:s16</code>: signed integer, 2 bytes, little-endian
+    # *   <code>:S16</code>: signed integer, 2 bytes, big-endian
+    # *   <code>:u32</code>: unsigned integer, 4 bytes, little-endian
+    # *   <code>:U32</code>: unsigned integer, 4 bytes, big-endian
+    # *   <code>:s32</code>: signed integer, 4 bytes, little-endian
+    # *   <code>:S32</code>: signed integer, 4 bytes, big-endian
+    # *   <code>:u64</code>: unsigned integer, 8 bytes, little-endian
+    # *   <code>:U64</code>: unsigned integer, 8 bytes, big-endian
+    # *   <code>:s64</code>: signed integer, 8 bytes, little-endian
+    # *   <code>:S64</code>: signed integer, 8 bytes, big-endian
+    # *   <code>:u128</code>: unsigned integer, 16 bytes, little-endian
+    # *   <code>:U128</code>: unsigned integer, 16 bytes, big-endian
+    # *   <code>:s128</code>: signed integer, 16 bytes, little-endian
+    # *   <code>:S128</code>: signed integer, 16 bytes, big-endian
+    # *   <code>:f32</code>: float, 4 bytes, little-endian
+    # *   <code>:F32</code>: float, 4 bytes, big-endian
+    # *   <code>:f64</code>: double, 8 bytes, little-endian
+    # *   <code>:F64</code>: double, 8 bytes, big-endian
     #
     # 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.
+    # in the buffer. For example, a <code>:u32</code> buffer type is a 32-bit
+    # unsigned integer in little-endian format.
     #
     #     string = [1.5].pack('f')
     #     # => "\x00\x00\xC0?"
@@ -546,7 +557,7 @@ class IO
     # -->
     # 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`.
+    # <code>-errno</code>.
     #
     # If `length` is not given or `nil`, it defaults to the size of the buffer minus
     # the offset, i.e. the entire buffer.
@@ -579,7 +590,7 @@ class IO
     # -->
     # 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`.
+    # <code>-errno</code>.
     #
     # If `length` is not given or `nil`, it defaults to the size of the buffer minus
     # the offset, i.e. the entire buffer.
@@ -596,7 +607,7 @@ class IO
     #     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.
+    # <code>output.txt</code>, starting from file position 2.
     #
     def pwrite: (untyped, untyped, untyped) -> untyped
 
@@ -605,7 +616,7 @@ class IO
     #   - 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`.
+    # `offset`. If an error occurs, return <code>-errno</code>.
     #
     # If `length` is not given or `nil`, it defaults to the size of the buffer minus
     # the offset, i.e. the entire buffer.
@@ -745,8 +756,8 @@ class IO
     # 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.
+    # Raises RuntimeError if the <code>offset+length</code> is out of the current
+    # buffer's bounds.
     #
     #     string = 'test'
     #     buffer = IO::Buffer.for(string).dup
@@ -830,7 +841,7 @@ class IO
     #   - 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`.
+    # `io`. If an error occurs, return <code>-errno</code>.
     #
     # If `length` is not given or `nil`, it defaults to the size of the buffer minus
     # the offset, i.e. the entire buffer.
@@ -843,7 +854,7 @@ class IO
     #     out = File.open('output.txt', 'wb')
     #     IO::Buffer.for('1234567').write(out, 3)
     #
-    # This leads to `123` being written into `output.txt`
+    # This leads to `123` being written into <code>output.txt</code>
     #
     def write: (untyped, untyped) -> untyped
 

data/core/io/wait.rbs

@@ -1,42 +1,24 @@
 %a{annotate:rdoc:skip}
 class IO
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
-  #   - io.nread -> int
-  # -->
-  # Returns number of bytes that can be read without blocking. Returns zero if no
-  # information available.
-  #
-  # You must require 'io/wait' to use this method.
-  #
-  def nread: () -> Integer
-
-  # <!--
-  #   rdoc-file=ext/io/wait/wait.c
-  #   - io.ready? -> truthy or falsy
-  # -->
-  # Returns a truthy value if input available without blocking, or a falsy value.
-  #
-  # You must require 'io/wait' to use this method.
-  #
-  def ready?: () -> boolish
-
-  # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait(events, timeout) -> event mask, false or nil
-  #   - io.wait(timeout = nil, mode = :read) -> self, true, or false
+  #   - io.wait(*event_symbols[, timeout]) -> self, true, or false
   # -->
   # Waits until the IO becomes ready for the specified events and returns the
   # subset of events that become ready, or a falsy value when times out.
   #
-  # The events can be a bit mask of `IO::READABLE`, `IO::WRITABLE` or
-  # `IO::PRIORITY`.
-  #
-  # Returns a truthy value immediately when buffered data is available.
+  # The events can be a bit mask of <code>IO::READABLE</code>,
+  # <code>IO::WRITABLE</code> or <code>IO::PRIORITY</code>.
   #
-  # Optional parameter `mode` is one of `:read`, `:write`, or `:read_write`.
+  # Returns an event mask (truthy value) immediately when buffered data is
+  # available.
   #
-  # You must require 'io/wait' to use this method.
+  # The second form: if one or more event symbols (<code>:read</code>,
+  # <code>:write</code>, or <code>:read_write</code>) are passed, the event mask
+  # is the bit OR of the bitmask corresponding to those symbols.  In this form,
+  # `timeout` is optional, the order of the arguments is arbitrary, and returns
+  # `io` if any of the events is ready.
   #
   def wait: (Integer events, ?Time::_Timeout timeout) -> (Integer | false | nil)
           | (?Time::_Timeout? timeout, *wait_mode mode) -> (self | true | false)
@@ -44,7 +26,7 @@ class IO
   type wait_mode = :read | :r | :readable | :write | :w | :writable | :read_write | :rw | :readable_writable
 
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait_readable          -> truthy or falsy
   #   - io.wait_readable(timeout) -> truthy or falsy
   # -->
@@ -52,19 +34,15 @@ class IO
   # times out.  Returns a truthy value immediately when buffered data is
   # available.
   #
-  # You must require 'io/wait' to use this method.
-  #
   def wait_readable: (?Time::_Timeout? timeout) -> boolish
 
   # <!--
-  #   rdoc-file=ext/io/wait/wait.c
+  #   rdoc-file=io.c
   #   - io.wait_writable          -> truthy or falsy
   #   - io.wait_writable(timeout) -> truthy or falsy
   # -->
   # Waits until IO is writable and returns a truthy value or a falsy value when
   # times out.
   #
-  # You must require 'io/wait' to use this method.
-  #
   def wait_writable: (?Time::_Timeout? timeout) -> boolish
 end