rbs 2.0.0 → 2.1.0

data/core/basic_object.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=object.c -->
 # BasicObject is the parent class of all classes in Ruby.  It's an explicit
 # blank class.
 #
@@ -24,7 +25,7 @@
 #       DELEGATE = [:puts, :p]
 #
 #       def method_missing(name, *args, &block)
-#         super unless DELEGATE.include? name
+#         return super unless DELEGATE.include? name
 #         ::Kernel.send(name, *args, &block)
 #       end
 #
@@ -44,21 +45,79 @@
 #       end
 #     end
 #
+# ### What's Here
+#
+# These are the methods defined for BasicObject:
+#
+#     ::new
+# :       Returns a new BasicObject instance.
+#
+#     [!](#method-i-21)
+# :       Returns the boolean negation of `self`: `true` or `false`.
+#
+#     [!=](#method-i-21-3D)
+# :       Returns whether `self` and the given object are *not* equal.
+#
+#     [==](#method-i-3D-3D)
+# :       Returns whether `self` and the given object are equivalent.
+#
+#     [__id__](#method-i-__id__)
+# :       Returns the integer object identifier for `self`.
+#
+#     [__send__](#method-i-__send__)
+# :       Calls the method identified by the given symbol.
+#
+#     #equal?
+# :       Returns whether `self` and the given object are the same object.
+#
+#     #instance_eval
+# :       Evaluates the given string or block in the context of `self`.
+#
+#     #instance_exec
+# :       Executes the given block in the context of `self`, passing the given
+#         arguments.
+#
+#     #method_missing
+# :       Method called when an undefined method is called on `self`.
+#
+#     #singleton_method_added
+# :       Method called when a singleton method is added to `self`.
+#
+#     #singleton_method_removed
+# :       Method called when a singleton method is added removed from `self`.
+#
+#     #singleton_method_undefined
+# :       Method called when a singleton method is undefined in `self`.
+#
 class BasicObject
+  # <!--
+  #   rdoc-file=object.c
+  #   - !obj    -> true or false
+  # -->
   # Boolean negate.
   #
   def !: () -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj != other        -> true or false
+  # -->
   # Returns true if two objects are not-equal, otherwise false.
   #
   def !=: (untyped other) -> bool
 
-  # Equality --- At the `Object` level, `==` returns `true` only if `obj` and
-  # `other` are the same object. Typically, this method is overridden in
-  # descendant classes to provide class-specific meaning.
-  #
-  # Unlike `==`, the `equal?` method should never be overridden by subclasses as
-  # it is used to determine object identity (that is, `a.equal?(b)` if and only if
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj == other        -> true or false
+  #   - obj.equal?(other)   -> true or false
+  #   - obj.eql?(other)     -> true or false
+  # -->
+  # Equality --- At the Object level, #== returns `true` only if `obj` and `other`
+  # are the same object.  Typically, this method is overridden in descendant
+  # classes to provide class-specific meaning.
+  #
+  # Unlike #==, the #equal? method should never be overridden by subclasses as it
+  # is used to determine object identity (that is, `a.equal?(b)` if and only if
   # `a` is the same object as `b`):
   #
   #     obj = "a"
@@ -68,18 +127,27 @@ class BasicObject
   #     obj.equal? other  #=> false
   #     obj.equal? obj    #=> true
   #
-  # The `eql?` method returns `true` if `obj` and `other` refer to the same hash
-  # key.  This is used by Hash to test members for equality.  For objects of class
-  # `Object`, `eql?` is synonymous with `==`.  Subclasses normally continue this
-  # tradition by aliasing `eql?` to their overridden `==` method, but there are
-  # exceptions.  `Numeric` types, for example, perform type conversion across
-  # `==`, but not across `eql?`, so:
+  # The #eql? method returns `true` if `obj` and `other` refer to the same hash
+  # key.  This is used by Hash to test members for equality.  For any pair of
+  # objects where #eql? returns `true`, the #hash value of both objects must be
+  # equal. So any subclass that overrides #eql? should also override #hash
+  # appropriately.
+  #
+  # For objects of class Object, #eql?  is synonymous with #==.  Subclasses
+  # normally continue this tradition by aliasing #eql? to their overridden #==
+  # method, but there are exceptions. Numeric types, for example, perform type
+  # conversion across #==, but not across #eql?, so:
   #
   #     1 == 1.0     #=> true
   #     1.eql? 1.0   #=> false
   #
   def ==: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=gc.c
+  #   - obj.__id__       -> integer
+  #   - obj.object_id    -> integer
+  # -->
   # Returns an integer identifier for `obj`.
   #
   # The same number will be returned on all calls to `object_id` for a given
@@ -88,6 +156,8 @@ class BasicObject
   # Note: that some objects of builtin classes are reused for optimization. This
   # is the case for immediate values and frozen string literals.
   #
+  # BasicObject implements +__id__+, Kernel implements `object_id`.
+  #
   # Immediate values are not passed by reference but are passed by value: `nil`,
   # `true`, `false`, Fixnums, Symbols, and some Floats.
   #
@@ -98,11 +168,21 @@ class BasicObject
   #
   def __id__: () -> Integer
 
+  # <!--
+  #   rdoc-file=vm_eval.c
+  #   - foo.send(symbol [, args...])       -> obj
+  #   - foo.__send__(symbol [, args...])   -> obj
+  #   - foo.send(string [, args...])       -> obj
+  #   - foo.__send__(string [, args...])   -> obj
+  # -->
   # Invokes the method identified by *symbol*, passing it any arguments specified.
-  # You can use `__send__` if the name `send` clashes with an existing method in
-  # *obj*. When the method is identified by a string, the string is converted to a
+  # When the method is identified by a string, the string is converted to a
   # symbol.
   #
+  # BasicObject implements +__send__+, Kernel implements `send`. `__send__` is
+  # safer than `send` when *obj* has the same method name like `Socket`. See also
+  # `public_send`.
+  #
   #     class Klass
   #       def hello(*args)
   #         "Hello " + args.join(' ')
@@ -113,12 +193,13 @@ class BasicObject
   #
   def __send__: (String | Symbol arg0, *untyped args) -> untyped
 
-  # Equality --- At the `Object` level, `==` returns `true` only if `obj` and
-  # `other` are the same object. Typically, this method is overridden in
-  # descendant classes to provide class-specific meaning.
+  # <!-- rdoc-file=object.c -->
+  # Equality --- At the Object level, #== returns `true` only if `obj` and `other`
+  # are the same object.  Typically, this method is overridden in descendant
+  # classes to provide class-specific meaning.
   #
-  # Unlike `==`, the `equal?` method should never be overridden by subclasses as
-  # it is used to determine object identity (that is, `a.equal?(b)` if and only if
+  # Unlike #==, the #equal? method should never be overridden by subclasses as it
+  # is used to determine object identity (that is, `a.equal?(b)` if and only if
   # `a` is the same object as `b`):
   #
   #     obj = "a"
@@ -128,18 +209,27 @@ class BasicObject
   #     obj.equal? other  #=> false
   #     obj.equal? obj    #=> true
   #
-  # The `eql?` method returns `true` if `obj` and `other` refer to the same hash
-  # key.  This is used by Hash to test members for equality.  For objects of class
-  # `Object`, `eql?` is synonymous with `==`.  Subclasses normally continue this
-  # tradition by aliasing `eql?` to their overridden `==` method, but there are
-  # exceptions.  `Numeric` types, for example, perform type conversion across
-  # `==`, but not across `eql?`, so:
+  # The #eql? method returns `true` if `obj` and `other` refer to the same hash
+  # key.  This is used by Hash to test members for equality.  For any pair of
+  # objects where #eql? returns `true`, the #hash value of both objects must be
+  # equal. So any subclass that overrides #eql? should also override #hash
+  # appropriately.
+  #
+  # For objects of class Object, #eql?  is synonymous with #==.  Subclasses
+  # normally continue this tradition by aliasing #eql? to their overridden #==
+  # method, but there are exceptions. Numeric types, for example, perform type
+  # conversion across #==, but not across #eql?, so:
   #
   #     1 == 1.0     #=> true
   #     1.eql? 1.0   #=> false
   #
   def equal?: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=vm_eval.c
+  #   - obj.instance_eval(string [, filename [, lineno]] )   -> obj
+  #   - obj.instance_eval {|obj| block }                     -> obj
+  # -->
   # Evaluates a string containing Ruby source code, or the given block, within the
   # context of the receiver (*obj*). In order to set the context, the variable
   # `self` is set to *obj* while the code is executing, giving the code access to
@@ -169,6 +259,10 @@ class BasicObject
   def instance_eval: (String, ?String filename, ?Integer lineno) -> untyped
                    | [U] () { (self) -> U } -> U
 
+  # <!--
+  #   rdoc-file=vm_eval.c
+  #   - obj.instance_exec(arg...) {|var...| block }                       -> obj
+  # -->
   # Executes the given block within the context of the receiver (*obj*). In order
   # to set the context, the variable `self` is set to *obj* while the code is
   # executing, giving the code access to *obj*'s instance variables.  Arguments
@@ -184,12 +278,20 @@ class BasicObject
   #
   def instance_exec: [U, V] (*V args) { (*V args) -> U } -> U
 
-  # Not documented
+  # <!--
+  #   rdoc-file=object.c
+  #   - BasicObject.new
+  # -->
+  # Returns a new BasicObject.
   #
   def initialize: () -> void
 
   private
 
+  # <!--
+  #   rdoc-file=vm_eval.c
+  #   - obj.method_missing(symbol [, *args] )   -> result
+  # -->
   # Invoked by Ruby when *obj* is sent a message it cannot handle. *symbol* is the
   # symbol for the method called, and *args* are any arguments that were passed to
   # it. By default, the interpreter raises an error when this method is called.
@@ -204,9 +306,14 @@ class BasicObject
   #       def roman_to_int(str)
   #         # ...
   #       end
-  #       def method_missing(methId)
-  #         str = methId.id2name
-  #         roman_to_int(str)
+  #
+  #       def method_missing(symbol, *args)
+  #         str = symbol.id2name
+  #         begin
+  #           roman_to_int(str)
+  #         rescue
+  #           super(symbol, *args)
+  #         end
   #       end
   #     end
   #
@@ -214,9 +321,14 @@ class BasicObject
   #     r.iv      #=> 4
   #     r.xxiii   #=> 23
   #     r.mm      #=> 2000
+  #     r.foo     #=> NoMethodError
   #
   def method_missing: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - singleton_method_added(symbol)
+  # -->
   # Invoked as a callback whenever a singleton method is added to the receiver.
   #
   #     module Chatty
@@ -236,6 +348,10 @@ class BasicObject
   #
   def singleton_method_added: (Symbol) -> void
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - singleton_method_removed(symbol)
+  # -->
   # Invoked as a callback whenever a singleton method is removed from the
   # receiver.
   #
@@ -259,6 +375,10 @@ class BasicObject
   #
   def singleton_method_removed: (Symbol) -> void
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - singleton_method_undefined(symbol)
+  # -->
   # Invoked as a callback whenever a singleton method is undefined in the
   # receiver.
   #

data/core/binding.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=proc.c -->
 # Objects of class Binding encapsulate the execution context at some particular
 # place in the code and retain this context for future use. The variables,
 # methods, value of `self`, and possibly an iterator block that can be accessed
@@ -33,6 +34,10 @@ class Binding
 
   def clone: () -> self
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.eval(string [, filename [,lineno]])  -> obj
+  # -->
   # Evaluates the Ruby expression(s) in *string*, in the *binding*'s context.  If
   # the optional *filename* and *lineno* parameters are present, they will be used
   # when reporting syntax errors.
@@ -45,6 +50,10 @@ class Binding
   #
   def eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/irb.rb
+  #   - irb()
+  # -->
   # Opens an IRB session where `binding.irb` is called which allows for
   # interactive debugging. You can call any methods or variables available in the
   # current scope, and mutate state if you need to.
@@ -103,6 +112,10 @@ class Binding
   #
   def irb: () -> void
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.local_variable_defined?(symbol) -> obj
+  # -->
   # Returns `true` if a local variable `symbol` exists.
   #
   #     def foo
@@ -117,6 +130,10 @@ class Binding
   #
   def local_variable_defined?: (String | Symbol symbol) -> bool
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.local_variable_get(symbol) -> obj
+  # -->
   # Returns the value of the local variable `symbol`.
   #
   #     def foo
@@ -131,6 +148,10 @@ class Binding
   #
   def local_variable_get: (String | Symbol symbol) -> untyped
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.local_variable_set(symbol, obj) -> obj
+  # -->
   # Set local variable named `symbol` as `obj`.
   #
   #     def foo
@@ -154,6 +175,10 @@ class Binding
   #
   def local_variable_set: [U] (String | Symbol symbol, U obj) -> U
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.local_variables -> Array
+  # -->
   # Returns the names of the binding's local variables as symbols.
   #
   #     def foo
@@ -169,10 +194,18 @@ class Binding
   #
   def local_variables: () -> Array[Symbol]
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.receiver    -> object
+  # -->
   # Returns the bound receiver of the binding object.
   #
   def receiver: () -> untyped
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - binding.source_location  -> [String, Integer]
+  # -->
   # Returns the Ruby source filename and line number of the binding object.
   #
   def source_location: () -> [ String, Integer ]

data/core/builtin.rbs

@@ -1,9 +1,9 @@
 interface _ToI
-  def to_i: -> Integer
+  def to_i: () -> Integer
 end
 
 interface _ToInt
-  def to_int: -> Integer
+  def to_int: () -> Integer
 end
 
 interface _ToR
@@ -11,7 +11,7 @@ interface _ToR
 end
 
 interface _ToS
-  def to_s: -> String
+  def to_s: () -> String
 end
 
 interface _ToStr
@@ -31,7 +31,7 @@ interface _ToPath
 end
 
 interface _Each[out A]
-  def each: { (A) -> void } -> void
+  def each: () { (A) -> void } -> void
 end
 
 interface _Reader

data/core/class.rbs

@@ -1,4 +1,4 @@
-# Extends any Class to include *json_creatable?* method.
+# <!-- rdoc-file=object.c -->
 # Classes in Ruby are first-class objects---each is an instance of class Class.
 #
 # Typically, you create a new class by using:
@@ -52,7 +52,13 @@
 #                  |                     |
 #     obj--->OtherClass---------->(OtherClass)-----------...
 #
+%a{annotate:rdoc:source:from=object.c}
 class Class < Module
+  # <!--
+  #   rdoc-file=object.c
+  #   - Class.new(super_class=Object)               -> a_class
+  #   - Class.new(super_class=Object) { |mod| ... } -> a_class
+  # -->
   # Creates a new anonymous (unnamed) class with the given superclass (or Object
   # if no parameter is given). You can give a class a name by assigning the class
   # object to a constant.
@@ -78,6 +84,10 @@ class Class < Module
   #
   def initialize: (?Class superclass) ?{ (Class newclass) -> void } -> void
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.allocate()   ->   obj
+  # -->
   # Allocates space for a new object of *class*'s class and does not call
   # initialize on the new instance. The returned object must be an instance of
   # *class*.
@@ -96,6 +106,10 @@ class Class < Module
   #
   def allocate: () -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - inherited(subclass)
+  # -->
   # Callback invoked whenever a subclass of the current class is created.
   #
   # Example:
@@ -119,12 +133,39 @@ class Class < Module
   #
   def inherited: (Class arg0) -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.new(args, ...)    ->  obj
+  # -->
   # Calls #allocate to create a new object of *class*'s class, then invokes that
   # object's #initialize method, passing it *args*.  This is the method that ends
   # up getting called whenever an object is constructed using `.new`.
   #
   def new: () -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - subclasses -> array
+  # -->
+  # Returns an array of classes where the receiver is the direct superclass of the
+  # class, excluding singleton classes. The order of the returned array is not
+  # defined.
+  #
+  #     class A; end
+  #     class B < A; end
+  #     class C < B; end
+  #     class D < A; end
+  #
+  #     A.subclasses        #=> [D, B]
+  #     B.subclasses        #=> [C]
+  #     C.subclasses        #=> []
+  #
+  def subclasses: () -> Array[Class]
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.superclass -> a_super_class or nil
+  # -->
   # Returns the superclass of *class*, or `nil`.
   #
   #     File.superclass          #=> IO
@@ -138,8 +179,5 @@ class Class < Module
   #
   #     BasicObject.superclass   #=> nil
   #
-  # # arglists
-  #     class.superclass -> a_super_class or nil
-  #
-  def `superclass`: () -> Class?
+  def superclass: () -> Class?
 end

data/core/comparable.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=compar.c -->
 # The Comparable mixin is used by classes whose objects may be ordered. The
 # class must define the `<=>` operator, which compares the receiver against
 # another object, returning a value less than 0, returning 0, or returning a
@@ -32,32 +33,83 @@
 #     s4.between?(s3, s5)           #=> true
 #     [ s3, s2, s5, s4, s1 ].sort   #=> [Z, YY, XXX, WWWW, VVVVV]
 #
+# ## What's Here
+#
+# Module Comparable provides these methods, all of which use method `<=>`:
+#
+#     [<](#method-i-3C)
+# :       Returns whether `self` is less than the given object.
+#
+#     [<=](#method-i-3C-3D)
+# :       Returns whether `self` is less than or equal to the given object.
+#
+#     [==](#method-i-3D-3D)
+# :       Returns whether `self` is equal to the given object.
+#
+#     [>](#method-i-3E)
+# :       Returns whether `self` is greater than or equal to the given object.
+#
+#     [>=](#method-i-3E-3D)
+# :       Returns whether `self` is greater than the given object.
+#
+# *   #between? Returns `true` if `self` is between two given objects.
+#     #clamp
+# :       For given objects `min` and `max`, or range `(min..max)`, returns:
+#
+#     *   `min` if `(self <=> min) < 0`.
+#     *   `max` if `(self <=> max) > 0`.
+#     *   `self` otherwise.
+#
 module Comparable : _WithSpaceshipOperator
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj < other    -> true or false
+  # -->
   # Compares two objects based on the receiver's `<=>` method, returning true if
   # it returns a value less than 0.
   #
   def <: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj <= other    -> true or false
+  # -->
   # Compares two objects based on the receiver's `<=>` method, returning true if
   # it returns a value less than or equal to 0.
   #
   def <=: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj == other    -> true or false
+  # -->
   # Compares two objects based on the receiver's `<=>` method, returning true if
   # it returns 0. Also returns true if *obj* and *other* are the same object.
   #
   def ==: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj > other    -> true or false
+  # -->
   # Compares two objects based on the receiver's `<=>` method, returning true if
   # it returns a value greater than 0.
   #
   def >: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj >= other    -> true or false
+  # -->
   # Compares two objects based on the receiver's `<=>` method, returning true if
   # it returns a value greater than or equal to 0.
   #
   def >=: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj.between?(min, max)    -> true or false
+  # -->
   # Returns `false` if *obj* `<=>` *min* is less than zero or if *obj* `<=>` *max*
   # is greater than zero, `true` otherwise.
   #
@@ -68,6 +120,11 @@ module Comparable : _WithSpaceshipOperator
   #
   def between?: (untyped min, untyped max) -> bool
 
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj.clamp(min, max) ->  obj
+  #   - obj.clamp(range)    ->  obj
+  # -->
   # In `(min, max)` form, returns *min* if *obj* `<=>` *min* is less than zero,
   # *max* if *obj* `<=>` *max* is greater than zero, and *obj* otherwise.
   #