rbs 2.0.0 → 2.1.0

data/core/object.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=object.c -->
 # Object is the default root of all Ruby objects.  Object inherits from
 # BasicObject which allows creating alternate object hierarchies.  Methods on
 # Object are available to all classes unless explicitly overridden.
@@ -13,39 +14,216 @@
 # In the descriptions of Object's methods, the parameter *symbol* refers to a
 # symbol, which is either a quoted string or a Symbol (such as `:name`).
 #
+# ## What's Here
+#
+# First, what's elsewhere. Class Object:
+#
+# *   Inherits from [class
+#     BasicObject](BasicObject.html#class-BasicObject-label-What-27s+Here).
+# *   Includes [module Kernel](Kernel.html#module-Kernel-label-What-27s+Here).
+#
+#
+# Here, class Object provides methods for:
+#
+# *   [Querying](#class-Object-label-Querying)
+# *   [Instance Variables](#class-Object-label-Instance+Variables)
+# *   [Other](#class-Object-label-Other)
+#
+#
+# ### Querying
+#
+#     [!~](#method-i-21~)
+# :       Returns `true` if `self` does not match the given object, otherwise
+#         `false`.
+#
+#     [<=>](#method-i-3C-3D-3E)
+# :       Returns 0 if `self` and the given object `object` are the same object,
+#         or if `self == object`; otherwise returns `nil`.
+#
+#     #===
+# :       Implements case equality, effectively the same as calling #==.
+#
+#     #eql?
+# :       Implements hash equality, effectively the same as calling #==.
+#
+#     #kind_of? (aliased as #is_a?)
+# :       Returns whether given argument is an ancestor of the singleton class
+#         of `self`.
+#
+#     #instance_of?
+# :       Returns whether `self` is an instance of the given class.
+#
+#     #instance_variable_defined?
+# :       Returns whether the given instance variable is defined in `self`.
+#
+#     #method
+# :       Returns the Method object for the given method in `self`.
+#
+#     #methods
+# :       Returns an array of symbol names of public and protected methods in
+#         `self`.
+#
+#     #nil?
+# :       Returns `false`. (Only `nil` responds `true` to method `nil?`.)
+#
+#     #object_id
+# :       Returns an integer corresponding to `self` that is unique for the
+#         current process
+#
+#     #private_methods
+# :       Returns an array of the symbol names of the private methods in `self`.
+#
+#     #protected_methods
+# :       Returns an array of the symbol names of the protected methods in
+#         `self`.
+#
+#     #public_method
+# :       Returns the Method object for the given public method in `self`.
+#
+#     #public_methods
+# :       Returns an array of the symbol names of the public methods in `self`.
+#
+#     #respond_to?
+# :       Returns whether `self` responds to the given method.
+#
+#     #singleton_class
+# :       Returns the singleton class of `self`.
+#
+#     #singleton_method
+# :       Returns the Method object for the given singleton method in `self`.
+#
+#     #singleton_methods
+# :       Returns an array of the symbol names of the singleton methods in
+#         `self`.
+#
+#
+#     #define_singleton_method
+# :       Defines a singleton method in `self` for the given symbol method-name
+#         and block or proc.
+#
+#     #extend
+# :       Includes the given modules in the singleton class of `self`.
+#
+#     #public_send
+# :       Calls the given public method in `self` with the given argument.
+#
+#     #send
+# :       Calls the given method in `self` with the given argument.
+#
+#
+#
+# ### Instance Variables
+#
+#     #instance_variable_get
+# :       Returns the value of the given instance variable in `self`, or `nil`
+#         if the instance variable is not set.
+#
+#     #instance_variable_set
+# :       Sets the value of the given instance variable in `self` to the given
+#         object.
+#
+#     #instance_variables
+# :       Returns an array of the symbol names of the instance variables in
+#         `self`.
+#
+#     #remove_instance_variable
+# :       Removes the named instance variable from `self`.
+#
+#
+#
+# ### Other
+#
+#     #clone
+# :       Returns a shallow copy of `self`, including singleton class and frozen
+#         state.
+#
+#     #define_singleton_method
+# :       Defines a singleton method in `self` for the given symbol method-name
+#         and block or proc.
+#
+#     #display
+# :       Prints `self` to the given IO stream or `$stdout`.
+#
+#     #dup
+# :       Returns a shallow unfrozen copy of `self`.
+#
+#     #enum_for (aliased as #to_enum)
+# :       Returns an Enumerator for `self` using the using the given method,
+#         arguments, and block.
+#
+#     #extend
+# :       Includes the given modules in the singleton class of `self`.
+#
+#     #freeze
+# :       Prevents further modifications to `self`.
+#
+#     #hash
+# :       Returns the integer hash value for `self`.
+#
+#     #inspect
+# :       Returns a human-readable  string representation of `self`.
+#
+#     #itself
+# :       Returns `self`.
+#
+#     #public_send
+# :       Calls the given public method in `self` with the given argument.
+#
+#     #send
+# :       Calls the given method in `self` with the given argument.
+#
+#     #to_s
+# :       Returns a string representation of `self`.
+#
 class Object < BasicObject
   include Kernel
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj !~ other  -> true or false
+  # -->
   # Returns true if two objects do not match (using the *=~* method), otherwise
   # false.
   #
   def !~: (untyped) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj <=> other -> 0 or nil
+  # -->
   # Returns 0 if `obj` and `other` are the same object or `obj == other`,
   # otherwise nil.
   #
-  # The `<=>` is used by various methods to compare objects, for example
+  # The #<=> is used by various methods to compare objects, for example
   # Enumerable#sort, Enumerable#max etc.
   #
-  # Your implementation of `<=>` should return one of the following values: -1, 0,
+  # Your implementation of #<=> should return one of the following values: -1, 0,
   # 1 or nil. -1 means self is smaller than other. 0 means self is equal to other.
   # 1 means self is bigger than other. Nil means the two values could not be
   # compared.
   #
-  # When you define `<=>`, you can include Comparable to gain the methods `<=`,
-  # `<`, `==`, `>=`, `>` and `between?`.
+  # When you define #<=>, you can include Comparable to gain the methods #<=, #<,
+  # #==, #>=, #> and #between?.
   #
   def <=>: (untyped) -> Integer?
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj === other   -> true or false
+  # -->
   # Case Equality -- For class Object, effectively the same as calling `#==`, but
   # typically overridden by descendants to provide meaningful semantics in `case`
   # statements.
   #
   def ===: (untyped) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj =~ other  -> nil
+  # -->
   # This method is deprecated.
   #
-  # This is not only unuseful but also troublesome because it may hide a type
+  # This is not only useless but also troublesome because it may hide a type
   # error.
   #
   def =~: (untyped) -> bool
@@ -56,7 +234,7 @@ class Object < BasicObject
   #     1.class      #=> Integer
   #     self.class   #=> Object
   #
-  def `class`: () -> untyped
+  def class: () -> untyped
 
   # Produces a shallow copy of *obj*---the instance variables of *obj* are copied,
   # but not the objects they reference. `clone` copies the frozen (unless :freeze
@@ -78,9 +256,15 @@ class Object < BasicObject
   #
   def clone: (?freeze: bool?) -> self
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - define_singleton_method(symbol, method) -> symbol
+  #   - define_singleton_method(symbol) { block } -> symbol
+  # -->
   # Defines a singleton method in the receiver. The *method* parameter can be a
   # `Proc`, a `Method` or an `UnboundMethod` object. If a block is specified, it
-  # is used as the method body.
+  # is used as the method body. If a block or a method has parameters, they're
+  # used as method parameters.
   #
   #     class A
   #       class << self
@@ -98,9 +282,17 @@ class Object < BasicObject
   #     guy.define_singleton_method(:hello) { "#{self}: Hello there!" }
   #     guy.hello    #=>  "Bob: Hello there!"
   #
+  #     chris = "Chris"
+  #     chris.define_singleton_method(:greet) {|greeting| "#{greeting}, I'm Chris!" }
+  #     chris.greet("Hi") #=> "Hi, I'm Chris!"
+  #
   def define_singleton_method: (Symbol, Method | UnboundMethod) -> Symbol
                              | (Symbol) { (*untyped) -> untyped } -> Symbol
 
+  # <!--
+  #   rdoc-file=io.c
+  #   - obj.display(port=$>)    -> nil
+  # -->
   # Prints *obj* on the given port (default `$>`). Equivalent to:
   #
   #     def display(port=$>)
@@ -121,17 +313,21 @@ class Object < BasicObject
   #
   def display: (?_Writeable port) -> void
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.dup -> an_object
+  # -->
   # Produces a shallow copy of *obj*---the instance variables of *obj* are copied,
-  # but not the objects they reference. `dup` copies the tainted state of *obj*.
+  # but not the objects they reference.
   #
   # This method may have class-specific behavior.  If so, that behavior will be
   # documented under the #`initialize_copy` method of the class.
   #
   # ### on dup vs clone
   #
-  # In general, `clone` and `dup` may have different semantics in descendant
-  # classes. While `clone` is used to duplicate an object, including its internal
-  # state, `dup` typically uses the class of the descendant object to create the
+  # In general, #clone and #dup may have different semantics in descendant
+  # classes. While #clone is used to duplicate an object, including its internal
+  # state, #dup typically uses the class of the descendant object to create the
   # new instance.
   #
   # When using #dup, any modules that the object has been extended with will not
@@ -149,16 +345,18 @@ class Object < BasicObject
   #     s1.extend(Foo) #=> #<Klass:0x401b3a38>
   #     s1.foo #=> "foo"
   #
-  #     s2 = s1.clone #=> #<Klass:0x401b3a38>
+  #     s2 = s1.clone #=> #<Klass:0x401be280>
   #     s2.foo #=> "foo"
   #
-  #     s3 = s1.dup #=> #<Klass:0x401b3a38>
-  #     s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401b3a38>
+  #     s3 = s1.dup #=> #<Klass:0x401c1084>
+  #     s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401c1084>
   #
   def dup: () -> self
 
+  # <!-- rdoc-file=enumerator.c -->
   # Creates a new Enumerator which will enumerate by calling `method` on `obj`,
-  # passing `args` if any.
+  # passing `args` if any. What was *yielded* by method becomes values of
+  # enumerator.
   #
   # If a block is given, it will be used to calculate the size of the enumerator
   # without the need to iterate it (see Enumerator#size).
@@ -177,6 +375,11 @@ class Object < BasicObject
   #     a = [1, 2, 3]
   #     some_method(a.to_enum)
   #
+  #     # String#split in block form is more memory-effective:
+  #     very_large_string.split("|") { |chunk| return chunk if chunk.include?('DATE') }
+  #     # This could be rewritten more idiomatically with to_enum:
+  #     very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first
+  #
   # It is typical to call to_enum when defining methods for a generic Enumerable,
   # in case no block is passed.
   #
@@ -208,8 +411,16 @@ class Object < BasicObject
   def enum_for: (Symbol method, *untyped args) ?{ (*untyped args) -> Integer } -> Enumerator[untyped, untyped]
               | () ?{ () -> Integer } -> Enumerator[untyped, self]
 
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - obj.to_enum(method = :each, *args)                 -> enum
+  #   - obj.enum_for(method = :each, *args)                -> enum
+  #   - obj.to_enum(method = :each, *args) {|*args| block} -> enum
+  #   - obj.enum_for(method = :each, *args){|*args| block} -> enum
+  # -->
   # Creates a new Enumerator which will enumerate by calling `method` on `obj`,
-  # passing `args` if any.
+  # passing `args` if any. What was *yielded* by method becomes values of
+  # enumerator.
   #
   # If a block is given, it will be used to calculate the size of the enumerator
   # without the need to iterate it (see Enumerator#size).
@@ -228,6 +439,11 @@ class Object < BasicObject
   #     a = [1, 2, 3]
   #     some_method(a.to_enum)
   #
+  #     # String#split in block form is more memory-effective:
+  #     very_large_string.split("|") { |chunk| return chunk if chunk.include?('DATE') }
+  #     # This could be rewritten more idiomatically with to_enum:
+  #     very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first
+  #
   # It is typical to call to_enum when defining methods for a generic Enumerable,
   # in case no block is passed.
   #
@@ -258,12 +474,18 @@ class Object < BasicObject
   #
   alias to_enum enum_for
 
-  # 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"
@@ -273,18 +495,26 @@ class Object < 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 eql?: (untyped) -> bool
 
+  # <!--
+  #   rdoc-file=eval.c
+  #   - obj.extend(module, ...)    -> obj
+  # -->
   # Adds to *obj* the instance methods from each module given as a parameter.
   #
   #     module Mod
@@ -304,11 +534,15 @@ class Object < BasicObject
   #     k.extend(Mod)   #=> #<Klass:0x401b3bc8>
   #     k.hello         #=> "Hello from Mod.\n"
   #
-  def `extend`: (*Module) -> self
+  def extend: (*Module) -> self
 
-  # Prevents further modifications to *obj*. A `RuntimeError` will be raised if
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.freeze    -> obj
+  # -->
+  # Prevents further modifications to *obj*. A FrozenError will be raised if
   # modification is attempted. There is no way to unfreeze a frozen object. See
-  # also `Object#frozen?`.
+  # also Object#frozen?.
   #
   # This method returns self.
   #
@@ -333,14 +567,38 @@ class Object < BasicObject
   #
   def frozen?: () -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.hash    -> integer
+  # -->
+  # Generates an Integer hash value for this object.  This function must have the
+  # property that `a.eql?(b)` implies `a.hash == b.hash`.
+  #
+  # The hash value is used along with #eql? by the Hash class to determine if two
+  # objects reference the same hash key.  Any hash value that exceeds the capacity
+  # of an Integer will be truncated before being used.
+  #
+  # The hash value for an object may not be identical across invocations or
+  # implementations of Ruby.  If you need a stable identifier across Ruby
+  # invocations and implementations you will need to generate one with a custom
+  # method.
+  #
+  # Certain core classes such as Integer use built-in hash calculations and do not
+  # call the #hash method when used as a hash key.
+  #
   def hash: () -> Integer
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.inspect   -> string
+  # -->
   # Returns a string containing a human-readable representation of *obj*. The
-  # default `inspect` shows the object's class name, an encoding of the object id,
-  # and a list of the instance variables and their values (by calling #inspect on
-  # each of them). User defined classes should override this method to provide a
-  # better representation of *obj*.  When overriding this method, it should return
-  # a string whose encoding is compatible with the default external encoding.
+  # default #inspect shows the object's class name, an encoding of its memory
+  # address, and a list of the instance variables and their values (by calling
+  # #inspect on each of them).  User defined classes should override this method
+  # to provide a better representation of *obj*.  When overriding this method, it
+  # should return a string whose encoding is compatible with the default external
+  # encoding.
   #
   #     [ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
   #     Time.new.inspect                 #=> "2008-03-08 19:43:39 +0900"
@@ -358,8 +616,12 @@ class Object < BasicObject
   #
   def inspect: () -> String
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.instance_of?(class)    -> true or false
+  # -->
   # Returns `true` if *obj* is an instance of the given class. See also
-  # `Object#kind_of?`.
+  # Object#kind_of?.
   #
   #     class A;     end
   #     class B < A; end
@@ -372,6 +634,11 @@ class Object < BasicObject
   #
   def instance_of?: (Module) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.instance_variable_defined?(symbol)    -> true or false
+  #   - obj.instance_variable_defined?(string)    -> true or false
+  # -->
   # Returns `true` if the given instance variable is defined in *obj*. String
   # arguments are converted to symbols.
   #
@@ -387,9 +654,14 @@ class Object < BasicObject
   #
   def instance_variable_defined?: (String | Symbol var) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.instance_variable_get(symbol)    -> obj
+  #   - obj.instance_variable_get(string)    -> obj
+  # -->
   # Returns the value of the given instance variable, or nil if the instance
   # variable is not set. The `@` part of the variable name should be included for
-  # regular instance variables. Throws a `NameError` exception if the supplied
+  # regular instance variables. Throws a NameError exception if the supplied
   # symbol is not valid as an instance variable name. String arguments are
   # converted to symbols.
   #
@@ -404,11 +676,16 @@ class Object < BasicObject
   #
   def instance_variable_get: (String | Symbol var) -> untyped
 
-  # Sets the instance variable named by *symbol* to the given object, thereby
-  # frustrating the efforts of the class's author to attempt to provide proper
-  # encapsulation. The variable does not have to exist prior to this call. If the
-  # instance variable name is passed as a string, that string is converted to a
-  # symbol.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.instance_variable_set(symbol, obj)    -> obj
+  #   - obj.instance_variable_set(string, obj)    -> obj
+  # -->
+  # Sets the instance variable named by *symbol* to the given object. This may
+  # circumvent the encapsulation intended by the author of the class, so it should
+  # be used with care. The variable does not have to exist prior to this call. If
+  # the instance variable name is passed as a string, that string is converted to
+  # a symbol.
   #
   #     class Fred
   #       def initialize(p1, p2)
@@ -422,6 +699,10 @@ class Object < BasicObject
   #
   def instance_variable_set: [X] (String | Symbol var, X value) -> X
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.instance_variables    -> array
+  # -->
   # Returns an array of instance variable names for the receiver. Note that simply
   # defining an accessor does not create the corresponding instance variable.
   #
@@ -435,6 +716,7 @@ class Object < BasicObject
   #
   def instance_variables: () -> Array[Symbol]
 
+  # <!-- rdoc-file=object.c -->
   # Returns `true` if *class* is the class of *obj*, or if *class* is one of the
   # superclasses of *obj* or modules included in *obj*.
   #
@@ -458,6 +740,11 @@ class Object < BasicObject
   #
   def is_a?: (Module) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.is_a?(class)       -> true or false
+  #   - obj.kind_of?(class)    -> true or false
+  # -->
   # Returns `true` if *class* is the class of *obj*, or if *class* is one of the
   # superclasses of *obj* or modules included in *obj*.
   #
@@ -481,17 +768,24 @@ class Object < BasicObject
   #
   alias kind_of? is_a?
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.itself    -> obj
+  # -->
   # Returns the receiver.
   #
   #     string = "my string"
   #     string.itself.object_id == string.object_id   #=> true
   #
-  def `itself`: () -> self
+  def itself: () -> self
 
-  # Looks up the named method as a receiver in *obj*, returning a `Method` object
-  # (or raising `NameError`). The `Method` object acts as a closure in *obj*'s
-  # object instance, so instance variables and the value of `self` remain
-  # available.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - obj.method(sym)    -> method
+  # -->
+  # Looks up the named method as a receiver in *obj*, returning a Method object
+  # (or raising NameError). The Method object acts as a closure in *obj*'s object
+  # instance, so instance variables and the value of `self` remain available.
   #
   #     class Demo
   #       def initialize(n)
@@ -510,8 +804,8 @@ class Object < BasicObject
   #     m = l.method("hello")
   #     m.call   #=> "Hello, @iv = Fred"
   #
-  # Note that `Method` implements `to_proc` method, which means it can be used
-  # with iterators.
+  # Note that Method implements `to_proc` method, which means it can be used with
+  # iterators.
   #
   #     [ 1, 2, 3 ].each(&method(:puts)) # => prints 3 lines to stdout
   #
@@ -524,11 +818,15 @@ class Object < BasicObject
   #
   def method: (String | Symbol name) -> Method
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.methods(regular=true)    -> array
+  # -->
   # Returns a list of the names of public and protected methods of *obj*. This
   # will include all the methods accessible in *obj*'s ancestors. If the optional
-  # parameter is `false`, it returns an array of *obj<i>'s public and protected
+  # parameter is `false`, it returns an array of *obj*'s public and protected
   # singleton methods, the array will not include methods in modules included in
-  # <i>obj*.
+  # *obj*.
   #
   #     class Klass
   #       def klass_method()
@@ -550,13 +848,22 @@ class Object < BasicObject
   #
   def methods: () -> Array[Symbol]
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.nil?               -> true or false
+  # -->
   # Only the object *nil* responds `true` to `nil?`.
   #
   #     Object.new.nil?   #=> false
   #     nil.nil?          #=> true
   #
-  def `nil?`: () -> bool
+  def nil?: () -> 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
@@ -565,6 +872,8 @@ class Object < 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.
   #
@@ -575,30 +884,52 @@ class Object < BasicObject
   #
   def object_id: () -> Integer
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.private_methods(all=true)   -> array
+  # -->
   # Returns the list of private methods accessible to *obj*. If the *all*
   # parameter is set to `false`, only those methods in the receiver will be
   # listed.
   #
   def private_methods: () -> Array[Symbol]
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.protected_methods(all=true)   -> array
+  # -->
   # Returns the list of protected methods accessible to *obj*. If the *all*
   # parameter is set to `false`, only those methods in the receiver will be
   # listed.
   #
   def protected_methods: () -> Array[Symbol]
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - obj.public_method(sym)    -> method
+  # -->
   # Similar to *method*, searches public method only.
   #
   def public_method: (name name) -> Method
 
+  # <!--
+  #   rdoc-file=vm_eval.c
+  #   - obj.public_send(symbol [, args...])  -> obj
+  #   - obj.public_send(string [, args...])  -> obj
+  # -->
   # Invokes the method identified by *symbol*, passing it any arguments specified.
   # Unlike send, public_send calls public methods only. When the method is
   # identified by a string, the string is converted to a symbol.
   #
   #     1.public_send(:puts, "hello")  # causes NoMethodError
   #
-  def `public_send`: (name name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
+  def public_send: (name name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.remove_instance_variable(symbol)    -> obj
+  #   - obj.remove_instance_variable(string)    -> obj
+  # -->
   # Removes the named instance variable from *obj*, returning that variable's
   # value. String arguments are converted to symbols.
   #
@@ -618,6 +949,11 @@ class Object < BasicObject
   #
   def remove_instance_variable: (name name) -> untyped
 
+  # <!--
+  #   rdoc-file=vm_method.c
+  #   - obj.respond_to?(symbol, include_all=false) -> true or false
+  #   - obj.respond_to?(string, include_all=false) -> true or false
+  # -->
   # Returns `true` if *obj* responds to the given method.  Private and protected
   # methods are included in the search only if the optional second parameter
   # evaluates to `true`.
@@ -633,11 +969,21 @@ class Object < BasicObject
   #
   def respond_to?: (name name, ?boolish include_all) -> bool
 
+  # <!--
+  #   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(' ')
@@ -646,8 +992,12 @@ class Object < BasicObject
   #     k = Klass.new
   #     k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"
   #
-  def `send`: (name name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
+  def send: (name name, *untyped args) ?{ (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.singleton_class    -> class
+  # -->
   # Returns the singleton class of *obj*.  This method creates a new singleton
   # class if *obj* does not have one.
   #
@@ -659,8 +1009,12 @@ class Object < BasicObject
   #     String.singleton_class      #=> #<Class:String>
   #     nil.singleton_class         #=> NilClass
   #
-  def `singleton_class`: () -> Class
+  def singleton_class: () -> Class
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - obj.singleton_method(sym)    -> method
+  # -->
   # Similar to *method*, searches singleton method only.
   #
   #     class Demo
@@ -682,6 +1036,10 @@ class Object < BasicObject
   #
   def singleton_method: (name name) -> Method
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.singleton_methods(all=true)    -> array
+  # -->
   # Returns an array of the names of singleton methods for *obj*. If the optional
   # *all* parameter is true, the list will include methods in modules included in
   # *obj*. Only public and protected singleton methods are returned.
@@ -711,31 +1069,35 @@ class Object < BasicObject
   #
   def singleton_methods: () -> Array[Symbol]
 
-  # Mark the object as tainted.
-  #
-  # Objects that are marked as tainted will be restricted from various built-in
-  # methods. This is to prevent insecure data, such as command-line arguments or
-  # strings read from Kernel#gets, from inadvertently compromising the user's
-  # system.
-  #
-  # To check whether an object is tainted, use #tainted?.
-  #
-  # You should only untaint a tainted object if your code has inspected it and
-  # determined that it is safe. To do so use #untaint.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.taint -> obj
+  # -->
+  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
   #
   def taint: () -> self
 
-  # Deprecated method that is equivalent to #taint.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.untrust -> obj
+  # -->
+  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
   #
   alias untrust taint
 
-  # Returns true if the object is tainted.
-  #
-  # See #taint for more information.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.tainted?    -> false
+  # -->
+  # Returns false.  This method is deprecated and will be removed in Ruby 3.2.
   #
   def tainted?: () -> bool
 
-  # Deprecated method that is equivalent to #tainted?.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.untrusted?    -> false
+  # -->
+  # Returns false.  This method is deprecated and will be removed in Ruby 3.2.
   #
   alias untrusted? tainted?
 
@@ -772,23 +1134,33 @@ class Object < BasicObject
   #     # does not meet condition, drop value
   #     2.yield_self.detect(&:odd?)            # => nil
   #
-  def `yield_self`: [X] () { (self) -> X } -> X
-                  | () -> Enumerator[self, untyped]
+  def yield_self: [X] () { (self) -> X } -> X
+                | () -> Enumerator[self, untyped]
 
-  # Returns a string representing *obj*. The default `to_s` prints the object's
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.to_s    -> string
+  # -->
+  # Returns a string representing *obj*. The default #to_s prints the object's
   # class and an encoding of the object id. As a special case, the top-level
   # object that is the initial execution context of Ruby programs returns
   # ``main''.
   #
   def to_s: () -> String
 
-  # Removes the tainted mark from the object.
-  #
-  # See #taint for more information.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.untaint    -> obj
+  # -->
+  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
   #
   def untaint: () -> self
 
-  # Deprecated method that is equivalent to #untaint.
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj.trust    -> obj
+  # -->
+  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
   #
   alias trust untaint