rbs 4.0.0.dev.4 → 4.1.0.pre.2

data/core/module.rbs

@@ -6,7 +6,7 @@
 # methods may not. (See Module#module_function.)
 #
 # In the descriptions that follow, the parameter *sym* refers to a symbol, which
-# is either a quoted string or a Symbol (such as `:name`).
+# is either a quoted string or a Symbol (such as <code>:name</code>).
 #
 #     module Mod
 #       include Math
@@ -19,7 +19,7 @@
 #     Mod.constants          #=> [:CONST, :PI, :E]
 #     Mod.instance_methods   #=> [:meth]
 #
-class Module < Object
+class Module
   # <!--
   #   rdoc-file=eval.c
   #   - Module.constants   -> array
@@ -40,7 +40,7 @@ class Module < Object
   #
   # The second form calls the instance method `constants`.
   #
-  def self.constants: () -> ::Array[Integer]
+  def self.constants: (?boolish inherit) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=eval.c
@@ -56,7 +56,7 @@ class Module < Object
   #     $a           #=> [M1::M2, M1]
   #     $a[0].name   #=> "M1::M2"
   #
-  def self.nesting: () -> ::Array[Module]
+  def self.nesting: () -> Array[Module]
 
   # <!--
   #   rdoc-file=eval.c
@@ -79,11 +79,11 @@ class Module < Object
   #     using B
   #     p Module.used_modules
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     [B, A]
   #
-  def self.used_modules: () -> ::Array[Module]
+  def self.used_modules: () -> Array[Module]
 
   # <!--
   #   rdoc-file=eval.c
@@ -106,7 +106,7 @@ class Module < Object
   #     using B
   #     p Module.used_refinements
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     [#<refinement:Object@B>, #<refinement:Object@A>]
   #
@@ -114,12 +114,15 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - mod < other   ->  true, false, or nil
+  #   - self < other -> true, false, or nil
   # -->
-  # Returns true if *mod* is a subclass of *other*. Returns `false` if *mod* is
-  # the same as *other* or *mod* is an ancestor of *other*. Returns `nil` if
-  # there's no relationship between the two. (Think of the relationship in terms
-  # of the class definition: "class A < B" implies "A < B".)
+  # Returns whether `self` is a subclass of `other`, or `nil` if there is no
+  # relationship between the two:
+  #
+  #     Float < Numeric # => true
+  #     Numeric < Float # => false
+  #     Float < Float   # => false
+  #     Float < Hash    # => nil
   #
   def <: (Module other) -> bool?
 
@@ -135,16 +138,32 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - module <=> other_module   -> -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Comparison---Returns -1, 0, +1 or nil depending on whether `module` includes
-  # `other_module`, they are the same, or if `module` is included by
-  # `other_module`.
+  # Compares `self` and `other`.
+  #
+  # Returns:
+  #
+  # *   <code>-1</code>, if `self` includes `other`, if or `self` is a subclass of
+  #     `other`.
+  # *   `0`, if `self` and `other` are the same.
+  # *   `1`, if `other` includes `self`, or if `other` is a subclass of `self`.
+  # *   `nil`, if none of the above is true.
+  #
+  # Examples:
   #
-  # Returns `nil` if `module` has no relationship with `other_module`, if
-  # `other_module` is not a module, or if the two values are incomparable.
+  #     # Class Array includes module Enumerable.
+  #              Array <=> Enumerable # => -1
+  #         Enumerable <=> Enumerable # =>  0
+  #         Enumerable <=> Array      # =>  1
+  #     # Class File is a subclass of class IO.
+  #               File <=> IO         # => -1
+  #               File <=> File       # =>  0
+  #                 IO <=> File       # =>  1
+  #     # Class File has no relationship to class String.
+  #               File <=> String     # => nil
   #
-  def <=>: (untyped other) -> Integer?
+  def <=>: (untyped other) -> (-1 | 0 | 1)?
 
   # <!--
   #   rdoc-file=object.c
@@ -157,8 +176,8 @@ class Module < Object
   # 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`):
+  # is used to determine object identity (that is, <code>a.equal?(b)</code> if and
+  # only if `a` is the same object as `b`):
   #
   #     obj = "a"
   #     other = obj.dup
@@ -231,11 +250,11 @@ class Module < Object
   #     include Mod
   #     exit(99)
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Exiting with code 99
   #
-  def alias_method: (interned new_name, interned old_name) -> ::Symbol
+  def alias_method: (interned new_name, interned old_name) -> Symbol
 
   # <!--
   #   rdoc-file=object.c
@@ -254,7 +273,7 @@ class Module < Object
   #     Math.ancestors       #=> [Math]
   #     Enumerable.ancestors #=> [Enumerable]
   #
-  def ancestors: () -> ::Array[Module]
+  def ancestors: () -> Array[Module]
 
   # <!--
   #   rdoc-file=eval.c
@@ -266,7 +285,7 @@ class Module < Object
   # module to *mod* if this module has not already been added to *mod* or one of
   # its ancestors. See also Module#include.
   #
-  def append_features: (Module arg0) -> self
+  private def append_features: (Module mod) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -274,17 +293,17 @@ class Module < Object
   #   - attr_accessor(string, ...)    -> array
   # -->
   # Defines a named attribute for this module, where the name is
-  # *symbol.*`id2name`, creating an instance variable (`@name`) and a
-  # corresponding access method to read it. Also creates a method called `name=`
-  # to set the attribute. String arguments are converted to symbols. Returns an
-  # array of defined method names as symbols.
+  # <em>symbol.</em>`id2name`, creating an instance variable (<code>@name</code>)
+  # and a corresponding access method to read it. Also creates a method called
+  # <code>name=</code> to set the attribute. String arguments are converted to
+  # symbols. Returns an array of defined method names as symbols.
   #
   #     module Mod
   #       attr_accessor(:one, :two) #=> [:one, :one=, :two, :two=]
   #     end
   #     Mod.instance_methods.sort   #=> [:one, :one=, :two, :two=]
   #
-  def attr_accessor: (*interned arg0) -> Array[Symbol]
+  def attr_accessor: (*interned names) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -294,11 +313,11 @@ class Module < Object
   #   - attr(string, ...)         -> array
   # -->
   # Creates instance variables and corresponding methods that return the value of
-  # each instance variable. Equivalent to calling ```attr`*:name*'' on each name
-  # in turn. String arguments are converted to symbols. Returns an array of
+  # each instance variable. Equivalent to calling ```attr`<em>:name</em>'' on each
+  # name in turn. String arguments are converted to symbols. Returns an array of
   # defined method names as symbols.
   #
-  def attr_reader: (*interned arg0) -> Array[Symbol]
+  def attr_reader: (*interned names) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -306,10 +325,10 @@ class Module < Object
   #   - attr_writer(string, ...)    -> array
   # -->
   # Creates an accessor method to allow assignment to the attribute
-  # *symbol*`.id2name`. String arguments are converted to symbols. Returns an
-  # array of defined method names as symbols.
+  # *symbol*<code>.id2name</code>. String arguments are converted to symbols.
+  # Returns an array of defined method names as symbols.
   #
-  def attr_writer: (*interned arg0) -> Array[Symbol]
+  def attr_writer: (*interned names) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=load.c
@@ -328,7 +347,9 @@ class Module < Object
   # replaced with *filename*.  If *const* is defined but not as autoload, does
   # nothing.
   #
-  def autoload: (interned _module, String filename) -> NilClass
+  # Files that are currently being loaded must not be registered for autoload.
+  #
+  def autoload: (interned constant, path filename) -> nil
 
   # <!--
   #   rdoc-file=load.c
@@ -370,14 +391,13 @@ class Module < Object
   #     puts Thing.new.hello()
   #     Thing.module_eval("invalid code", "dummy", 123)
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Hello there!
   #     dummy:123:in `module_eval': undefined local variable
   #         or method `code' for Thing:Class
   #
-  def class_eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
-                | [U] () { (self m) [self: self] -> U } -> U
+  alias class_eval module_eval
 
   # <!-- rdoc-file=vm_eval.c -->
   # Evaluates the given block in the context of the class/module. The method
@@ -392,11 +412,11 @@ class Module < Object
   #     }
   #     puts Thing.new.hello()
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Hello there!
   #
-  def class_exec: [U] (*untyped, **untyped) { (?) [self: self] -> U } -> U
+  alias class_exec module_exec
 
   # <!--
   #   rdoc-file=object.c
@@ -412,7 +432,7 @@ class Module < Object
   #     Fred.class_variable_defined?(:@@foo)    #=> true
   #     Fred.class_variable_defined?(:@@bar)    #=> false
   #
-  def class_variable_defined?: (interned arg0) -> bool
+  def class_variable_defined?: (interned name) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -420,15 +440,15 @@ class Module < Object
   #   - mod.class_variable_get(string)    -> obj
   # -->
   # Returns the value of the given class variable (or throws a NameError
-  # exception). The `@@` part of the variable name should be included for regular
-  # class variables. String arguments are converted to symbols.
+  # exception). The <code>@@</code> part of the variable name should be included
+  # for regular class variables. String arguments are converted to symbols.
   #
   #     class Fred
   #       @@foo = 99
   #     end
   #     Fred.class_variable_get(:@@foo)     #=> 99
   #
-  def class_variable_get: (interned arg0) -> untyped
+  def class_variable_get: (interned name) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -447,7 +467,7 @@ class Module < Object
   #     Fred.class_variable_set(:@@foo, 101)     #=> 101
   #     Fred.new.foo                             #=> 101
   #
-  def class_variable_set: (interned arg0, untyped arg1) -> untyped
+  def class_variable_set: [T] (interned name, T value) -> T
 
   # <!--
   #   rdoc-file=object.c
@@ -467,7 +487,7 @@ class Module < Object
   #     Two.class_variables          #=> [:@@var2, :@@var1]
   #     Two.class_variables(false)   #=> [:@@var2]
   #
-  def class_variables: (?boolish inherit) -> ::Array[Symbol]
+  def class_variables: (?boolish inherit) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -483,11 +503,36 @@ class Module < Object
   #       FOO = 1
   #     end
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Added :FOO
   #
-  def const_added: (Symbol) -> void
+  # If we define a class using the `class` keyword, `const_added` runs before
+  # `inherited`:
+  #
+  #     module M
+  #       def self.const_added(const_name)
+  #         super
+  #         p :const_added
+  #       end
+  #
+  #       parent = Class.new do
+  #         def self.inherited(subclass)
+  #           super
+  #           p :inherited
+  #         end
+  #       end
+  #
+  #       class Child < parent
+  #       end
+  #     end
+  #
+  # <em>produces:</em>
+  #
+  #     :const_added
+  #     :inherited
+  #
+  private def const_added: (Symbol const_name) -> void
 
   # <!--
   #   rdoc-file=object.c
@@ -590,10 +635,11 @@ class Module < Object
   #
   # In the next example, when a reference is made to an undefined constant,
   # `const_missing` attempts to load a file whose path is the lowercase version of
-  # the constant name (thus class `Fred` is assumed to be in file `fred.rb`). If
-  # defined as a side-effect of loading the file, the method returns the value
-  # stored in the constant. This implements an autoload feature similar to
-  # Kernel#autoload and Module#autoload, though it differs in important ways.
+  # the constant name (thus class `Fred` is assumed to be in file
+  # <code>fred.rb</code>). If defined as a side-effect of loading the file, the
+  # method returns the value stored in the constant. This implements an autoload
+  # feature similar to Kernel#autoload and Module#autoload, though it differs in
+  # important ways.
   #
   #     def Object.const_missing(name)
   #       @looked_for ||= {}
@@ -605,7 +651,7 @@ class Module < Object
   #       const_get(name, false)
   #     end
   #
-  def const_missing: (Symbol arg0) -> untyped
+  def const_missing: (Symbol name) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -623,7 +669,7 @@ class Module < Object
   #
   #     Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar
   #
-  def const_set: (interned arg0, untyped arg1) -> untyped
+  def const_set: [T] (interned name, T value) -> T
 
   # <!--
   #   rdoc-file=object.c
@@ -635,7 +681,8 @@ class Module < Object
   # If the constant is found, but its source location can not be extracted
   # (constant is defined in C code), empty array is returned.
   #
-  # *inherit* specifies whether to lookup in `mod.ancestors` (`true` by default).
+  # *inherit* specifies whether to lookup in <code>mod.ancestors</code> (`true` by
+  # default).
   #
   #     # test.rb:
   #     class A         # line 1
@@ -691,7 +738,7 @@ class Module < Object
   #
   # Also see Module#const_defined?.
   #
-  def constants: (?boolish inherit) -> ::Array[Symbol]
+  def constants: (?boolish inherit) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=proc.c
@@ -724,7 +771,7 @@ class Module < Object
   #     a.create_method(:betty) { p self }
   #     a.betty
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     In Fred
   #     Charge it!
@@ -751,9 +798,7 @@ class Module < Object
   #     HTTP::NOT_FOUND
   #     # warning: constant HTTP::NOT_FOUND is deprecated
   #
-  def deprecate_constant: (*interned) -> self
-
-  def eql?: (untyped other) -> bool
+  def deprecate_constant: (*interned names) -> self
 
   def equal?: (untyped other) -> bool
 
@@ -778,12 +823,12 @@ class Module < Object
   #     (s = Array.new).extend Picky  # Call Object.extend
   #     (s = "quick brown fox").extend Picky
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Picky added to Array
   #     Can't add Picky to a String
   #
-  def extend_object: (untyped arg0) -> untyped
+  private def extend_object: [T] (T object) -> T
 
   # <!--
   #   rdoc-file=object.c
@@ -801,7 +846,7 @@ class Module < Object
   #     end
   #      # => prints "A extended in Enumerable"
   #
-  def extended: (Module othermod) -> untyped
+  private def extended: (untyped othermod) -> void
 
   # <!--
   #   rdoc-file=object.c
@@ -819,7 +864,7 @@ class Module < Object
   # -->
   # Invokes Module.append_features on each parameter in reverse order.
   #
-  def include: (Module, *Module arg0) -> self
+  def include: (Module module, *Module additional_modules) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -846,8 +891,8 @@ class Module < Object
   #   - included(othermod)
   # -->
   # Callback invoked whenever the receiver is included in another module or class.
-  # This should be used in preference to `Module.append_features` if your code
-  # wants to perform some action when a module is included in another.
+  # This should be used in preference to <code>Module.append_features</code> if
+  # your code wants to perform some action when a module is included in another.
   #
   #     module A
   #       def A.included(mod)
@@ -859,7 +904,7 @@ class Module < Object
   #     end
   #      # => prints "A included in Enumerable"
   #
-  def included: (Module othermod) -> untyped
+  private def included: (Module othermod) -> void
 
   # <!--
   #   rdoc-file=object.c
@@ -882,7 +927,7 @@ class Module < Object
   #     Mixin.included_modules   #=> [Sub]
   #     Outer.included_modules   #=> [Sub, Mixin]
   #
-  def included_modules: () -> ::Array[Module]
+  def included_modules: () -> Array[Module]
 
   # <!--
   #   rdoc-file=object.c
@@ -909,8 +954,9 @@ class Module < Object
   # Assign the module to a constant (name starting uppercase) if you want to treat
   # it like a regular module.
   #
-  def initialize: () -> void
-                | () { (Module arg0) -> untyped } -> void
+  def initialize: () ?{ (Module mod) [self: self] -> void } -> void
+
+  def initialize_clone: (Module source, ?freeze: bool?) -> void
 
   # <!--
   #   rdoc-file=proc.c
@@ -937,11 +983,11 @@ class Module < Object
   #     interpreter = Interpreter.new
   #     interpreter.interpret('dave')
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Hello there, Dave!
   #
-  def instance_method: (interned arg0) -> UnboundMethod
+  def instance_method: (interned name) -> UnboundMethod
 
   # <!--
   #   rdoc-file=object.c
@@ -978,7 +1024,7 @@ class Module < Object
   #     end
   #     C.instance_methods(false).sort               #=> [:method2, :method3, :method4]
   #
-  def instance_methods: (?boolish include_super) -> ::Array[Symbol]
+  def instance_methods: (?boolish include_super) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -994,11 +1040,11 @@ class Module < Object
   #       def some_instance_method() end
   #     end
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Adding :some_instance_method
   #
-  def method_added: (Symbol meth) -> untyped
+  private def method_added: (Symbol method_name) -> void
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1055,11 +1101,36 @@ class Module < Object
   #       remove_method :some_instance_method
   #     end
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Removing :some_instance_method
   #
-  def method_removed: (Symbol method_name) -> untyped
+  private def method_removed: (Symbol method_name) -> void
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - method_undefined(method_name)
+  # -->
+  # Invoked as a callback whenever an instance method is undefined from the
+  # receiver.
+  #
+  #     module Chatty
+  #       def self.method_undefined(method_name)
+  #         puts "Undefining #{method_name.inspect}"
+  #       end
+  #       def self.some_class_method() end
+  #       def some_instance_method() end
+  #       class << self
+  #         undef_method :some_class_method
+  #       end
+  #       undef_method :some_instance_method
+  #     end
+  #
+  # <em>produces:</em>
+  #
+  #     Undefining :some_instance_method
+  #
+  private def method_undefined: (Symbol method_name) -> void
 
   # <!--
   #   rdoc-file=vm_eval.c
@@ -1081,14 +1152,14 @@ class Module < Object
   #     puts Thing.new.hello()
   #     Thing.module_eval("invalid code", "dummy", 123)
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Hello there!
   #     dummy:123:in `module_eval': undefined local variable
   #         or method `code' for Thing:Class
   #
-  def module_eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
-                 | [U] () { (self m) [self: self] -> U } -> U
+  def module_eval: (string code, ?string? filename, ?int lineno) -> untyped
+                 | [U] () { (self mod) [self: self] -> U } -> U
 
   # <!--
   #   rdoc-file=vm_eval.c
@@ -1107,7 +1178,7 @@ class Module < Object
   #     }
   #     puts Thing.new.hello()
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Hello there!
   #
@@ -1152,11 +1223,13 @@ class Module < Object
   #     Mod.one     #=> "This is one"
   #     c.call_one  #=> "This is the new one"
   #
-  def module_function: () -> nil
-                     | (Symbol method_name) -> Symbol
-                     | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
-                     | (string method_name) -> string
-                     | (interned, interned, *interned method_name) -> Array[interned]
+  private def module_function: () -> nil
+                             | (Symbol method_name) -> Symbol
+                             | [T < _ToStr] (T method_name) -> T
+                             | (interned method_name) -> interned
+                             | (Symbol, Symbol, *Symbol method_names) -> Array[Symbol]
+                             | [T < _ToStr] (T, T, *T method_names) -> Array[T]
+                             | (interned, interned, *interned method_names) -> Array[interned]
 
   # <!--
   #   rdoc-file=object.c
@@ -1172,7 +1245,7 @@ class Module < Object
   # -->
   # Invokes Module.prepend_features on each parameter in reverse order.
   #
-  def prepend: (Module, *Module arg0) -> self
+  def prepend: (Module module, *Module additional_modules) -> self
 
   # <!--
   #   rdoc-file=eval.c
@@ -1184,7 +1257,7 @@ class Module < Object
   # this module to *mod* if this module has not already been added to *mod* or one
   # of its ancestors. See also Module#prepend.
   #
-  def prepend_features: (Module arg0) -> self
+  private def prepend_features: (Module mod) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1202,7 +1275,7 @@ class Module < Object
   #     end
   #      # => prints "A prepended to Enumerable"
   #
-  def prepended: (Module othermod) -> untyped
+  private def prepended: (Module othermod) -> void
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1227,14 +1300,18 @@ class Module < Object
   #     end
   #     Mod.private_instance_methods   #=> [:a, :c]
   #
-  # Note that to show a private method on RDoc, use `:doc:`.
+  # Note that to show a private method on RDoc, use <code>:doc:</code>.
   #
-  def private: () -> nil
-             | (Symbol method_name) -> Symbol
-             | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
-             | (string method_name) -> string
-             | (interned, interned, *interned method_name) -> Array[interned]
-             | (Array[interned]) -> Array[interned]
+  private def private: () -> nil
+                     | (Symbol method_name) -> Symbol
+                     | [T < _ToStr] (T method_name) -> T
+                     | (interned method_name) -> interned
+                     | (Symbol, Symbol, *Symbol method_names) -> Array[Symbol]
+                     | [T < _ToStr] (T, T, *T method_names) -> Array[T]
+                     | (interned, interned, *interned method_names) -> Array[interned]
+                     | (Array[Symbol] method_names) -> Array[Symbol]
+                     | [T < _ToStr] (Array[T] method_names) -> Array[T]
+                     | (Array[interned] method_names) -> Array[interned]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1256,8 +1333,8 @@ class Module < Object
   #       end
   #     end
   #
-  def private_class_method: (*interned arg0) -> self
-                          | (Array[interned] arg0) -> self
+  def private_class_method: (*interned method_names) -> self
+                          | (Array[interned] method_names) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1265,7 +1342,7 @@ class Module < Object
   # -->
   # Makes a list of existing constants private.
   #
-  def private_constant: (*interned arg0) -> self
+  def private_constant: (*interned names) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1282,7 +1359,7 @@ class Module < Object
   #     Mod.instance_methods           #=> [:method2]
   #     Mod.private_instance_methods   #=> [:method1]
   #
-  def private_instance_methods: (?boolish include_super) -> ::Array[Symbol]
+  def private_instance_methods: (?boolish include_super) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1321,28 +1398,65 @@ class Module < Object
   #   - protected(method_name, method_name, ...) -> array
   #   - protected(array)                         -> array
   # -->
-  # With no arguments, sets the default visibility for subsequently defined
-  # methods to protected. With arguments, sets the named methods to have protected
-  # visibility. String arguments are converted to symbols. An Array of Symbols
-  # and/or Strings is also accepted. If a single argument is passed, it is
-  # returned. If no argument is passed, nil is returned. If multiple arguments are
-  # passed, the arguments are returned as an array.
+  # Sets the visibility of a section or of a list of method names as protected.
+  # Accepts no arguments, a splat of method names (symbols or strings) or an array
+  # of method names. Returns the arguments that it received.
+  #
+  # ## Important difference between protected in other languages
+  #
+  # Protected methods in Ruby are different from other languages such as Java,
+  # where methods are marked as protected to give access to subclasses. In Ruby,
+  # subclasses **already have access to all methods defined in the parent class**,
+  # even private ones.
+  #
+  # Marking a method as protected allows **different objects of the same class**
+  # to call it.
+  #
+  # One use case is for comparison methods, such as <code>==</code>, if we want to
+  # expose a method for comparison between objects of the same class without
+  # making the method public to objects of other classes.
+  #
+  # ## Performance considerations
+  #
+  # Protected methods are slower than others because they can't use inline cache.
   #
-  # If a method has protected visibility, it is callable only where `self` of the
-  # context is the same as the method. (method definition or instance_eval). This
-  # behavior is different from Java's protected method. Usually `private` should
-  # be used.
+  # ## Example
   #
-  # Note that a protected method is slow because it can't use inline cache.
+  #     class Account
+  #       # Mark balance as protected, so that we can compare between accounts
+  #       # without making it public.
+  #       attr_reader :balance
+  #       protected :balance
   #
-  # To show a private method on RDoc, use `:doc:` instead of this.
+  #       def initialize(balance)
+  #         @balance = balance
+  #       end
+  #
+  #       def >(other)
+  #         # The invocation to `other.balance` is allowed because `other` is a
+  #         # different object of the same class (Account).
+  #         balance > other.balance
+  #       end
+  #     end
+  #
+  #     account1 = Account.new(100)
+  #     account2 = Account.new(50)
   #
-  def protected: () -> nil
-               | (Symbol method_name) -> Symbol
-               | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
-               | (string method_name) -> string
-               | (interned, interned, *interned method_name) -> Array[interned]
-               | (Array[interned]) -> Array[interned]
+  #     account1 > account2  # => true (works)
+  #     account1.balance     # => NoMethodError (fails because balance is not public)
+  #
+  # To show a private method on RDoc, use <code>:doc:</code> instead of this.
+  #
+  private def protected: () -> nil
+                       | (Symbol method_name) -> Symbol
+                       | [T < _ToStr] (T method_name) -> T
+                       | (interned method_name) -> interned
+                       | (Symbol, Symbol, *Symbol method_names) -> Array[Symbol]
+                       | [T < _ToStr] (T, T, *T method_names) -> Array[T]
+                       | (interned, interned, *interned method_names) -> Array[interned]
+                       | (Array[Symbol] method_names) -> Array[Symbol]
+                       | [T < _ToStr] (Array[T] method_names) -> Array[T]
+                       | (Array[interned] method_names) -> Array[interned]
 
   # <!--
   #   rdoc-file=object.c
@@ -1351,7 +1465,7 @@ class Module < Object
   # Returns a list of the protected instance methods defined in *mod*. If the
   # optional parameter is `false`, the methods of any ancestors are not included.
   #
-  def protected_instance_methods: (?boolish include_super) -> ::Array[Symbol]
+  def protected_instance_methods: (?boolish include_super) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1397,12 +1511,16 @@ class Module < Object
   # returned. If no argument is passed, nil is returned. If multiple arguments are
   # passed, the arguments are returned as an array.
   #
-  def public: () -> nil
-            | (Symbol method_name) -> Symbol
-            | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
-            | (string method_name) -> string
-            | (interned, interned, *interned method_name) -> Array[interned]
-            | (Array[interned]) -> Array[interned]
+  private def public: () -> nil
+                    | (Symbol method_name) -> Symbol
+                    | [T < _ToStr] (T method_name) -> T
+                    | (interned method_name) -> interned
+                    | (Symbol, Symbol, *Symbol method_names) -> Array[Symbol]
+                    | [T < _ToStr] (T, T, *T method_names) -> Array[T]
+                    | (interned, interned, *interned method_names) -> Array[interned]
+                    | (Array[Symbol] method_names) -> Array[Symbol]
+                    | [T < _ToStr] (Array[T] method_names) -> Array[T]
+                    | (Array[interned] method_names) -> Array[interned]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1415,8 +1533,8 @@ class Module < Object
   # String arguments are converted to symbols. An Array of Symbols and/or Strings
   # is also accepted.
   #
-  def public_class_method: (*interned arg0) -> self
-                         | (Array[interned] arg0) -> self
+  def public_class_method: (*interned method_names) -> self
+                         | (Array[interned] method_names) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1424,7 +1542,7 @@ class Module < Object
   # -->
   # Makes a list of existing constants public.
   #
-  def public_constant: (*interned arg0) -> self
+  def public_constant: (*interned names) -> self
 
   # <!--
   #   rdoc-file=proc.c
@@ -1441,7 +1559,7 @@ class Module < Object
   # Returns a list of the public instance methods defined in *mod*. If the
   # optional parameter is `false`, the methods of any ancestors are not included.
   #
-  def public_instance_methods: (?boolish include_super) -> ::Array[Symbol]
+  def public_instance_methods: (?boolish include_super) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1481,7 +1599,7 @@ class Module < Object
   #
   # Returns a module, where refined methods are defined.
   #
-  def refine: (Module mod) { () [self: Refinement] -> void } -> Refinement
+  private def refine: (Module mod) { () [self: Refinement] -> void } -> Refinement
 
   # <!--
   #   rdoc-file=eval.c
@@ -1499,7 +1617,7 @@ class Module < Object
   #
   #     p A.refinements
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     [#<refinement:Integer@A>, #<refinement:String@A>]
   #
@@ -1518,12 +1636,12 @@ class Module < Object
   #       p(defined? @@var)
   #     end
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     99
   #     nil
   #
-  def remove_class_variable: (interned arg0) -> untyped
+  def remove_class_variable: (interned name) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -1533,7 +1651,7 @@ class Module < Object
   # previous value.  If that constant referred to a module, this will not change
   # that module's name and can lead to confusion.
   #
-  def remove_const: (interned arg0) -> untyped
+  private def remove_const: (interned name) -> untyped
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1543,7 +1661,44 @@ class Module < Object
   # Removes the method identified by *symbol* from the current class. For an
   # example, see Module#undef_method. String arguments are converted to symbols.
   #
-  def remove_method: (*interned arg0) -> self
+  def remove_method: (*interned method_names) -> self
+
+  # <!--
+  #   rdoc-file=vm_method.c
+  #   - ruby2_keywords(method_name, ...)    -> nil
+  # -->
+  # For the given method names, marks the method as passing keywords through a
+  # normal argument splat.  This should only be called on methods that accept an
+  # argument splat (<code>*args</code>) but not explicit keywords or a keyword
+  # splat.  It marks the method such that if the method is called with keyword
+  # arguments, the final hash argument is marked with a special flag such that if
+  # it is the final element of a normal argument splat to another method call, and
+  # that method call does not include explicit keywords or a keyword splat, the
+  # final element is interpreted as keywords. In other words, keywords will be
+  # passed through the method to other methods.
+  #
+  # This should only be used for methods that delegate keywords to another method,
+  # and only for backwards compatibility with Ruby versions before 3.0. See
+  # https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyw
+  # ord-arguments-in-ruby-3-0/ for details on why `ruby2_keywords` exists and when
+  # and how to use it.
+  #
+  # This method will probably be removed at some point, as it exists only for
+  # backwards compatibility. As it does not exist in Ruby versions before 2.7,
+  # check that the module responds to this method before calling it:
+  #
+  #     module Mod
+  #       def foo(meth, *args, &block)
+  #         send(:"do_#{meth}", *args, &block)
+  #       end
+  #       ruby2_keywords(:foo) if respond_to?(:ruby2_keywords, true)
+  #     end
+  #
+  # However, be aware that if the `ruby2_keywords` method is removed, the behavior
+  # of the `foo` method using the above approach will change so that the method
+  # does not pass through keywords.
+  #
+  private def ruby2_keywords: (interned method_name, *interned more_method_names) -> nil
 
   # <!--
   #   rdoc-file=object.c
@@ -1578,7 +1733,7 @@ class Module < Object
   #     m.name #=> nil
   #
   #     c = Class.new
-  #     c.set_temporary_name("MyClass(with description)")
+  #     c.set_temporary_name("MyClass(with description)") # => MyClass(with description)
   #
   #     c.new # => #<MyClass(with description):0x0....>
   #
@@ -1592,7 +1747,7 @@ class Module < Object
   #     C::M.name #=> "C::M"
   #     c.new # => #<C:0x0....>
   #
-  def set_temporary_name: (string?) -> self
+  def set_temporary_name: (string? name) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1652,7 +1807,7 @@ class Module < Object
   #     end
   #     c.hello
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     In child
   #     In parent
@@ -1676,14 +1831,14 @@ class Module < Object
   # Import class refinements from *module* into the current class or module
   # definition.
   #
-  def using: (Module arg0) -> self
+  private def using: (Module mod) -> self
 
   # <!-- rdoc-file=object.c -->
   # Returns a string representing this module or class. For basic classes and
   # modules, this is the name. For singletons, we show information on the thing
   # we're attached to as well.
   #
-  def inspect: () -> String
+  alias inspect to_s
 
   # <!--
   #   rdoc-file=object.c
@@ -1692,13 +1847,10 @@ class Module < Object
   #   - attr(name, false) -> array
   # -->
   # The first form is equivalent to #attr_reader. The second form is equivalent to
-  # `attr_accessor(name)` but deprecated. The last form is equivalent to
-  # `attr_reader(name)` but deprecated. Returns an array of defined method names
-  # as symbols.
+  # <code>attr_accessor(name)</code> but deprecated. The last form is equivalent
+  # to <code>attr_reader(name)</code> but deprecated. Returns an array of defined
+  # method names as symbols.
   #
-  def attr: (*interned arg0) -> Array[Symbol]
-
-  # A previous incarnation of `interned` for backward-compatibility (see #1499)
-  %a{deprecated: Use `interned`}
-  type id = interned
+  def attr: %a{deprecated} (interned name, bool create_writer) -> Array[Symbol]
+          | (*interned names) -> Array[Symbol]
 end