rbs 3.10.2 → 4.0.0.dev.1

data/core/kernel.rbs

@@ -80,7 +80,7 @@
 # *   #print: Prints the given objects to standard output without a newline.
 # *   #printf: Prints the string resulting from applying the given format string
 #     to any additional arguments.
-# *   #putc: Equivalent to `$stdout.putc(object)` for the given object.
+# *   #putc: Equivalent to <tt.$stdout.putc(object)</tt> for the given object.
 # *   #puts: Equivalent to `$stdout.puts(*objects)` for the given objects.
 # *   #readline: Similar to #gets, but raises an exception at the end of file.
 # *   #readlines: Returns an array of the remaining lines from the current
@@ -718,14 +718,14 @@ module Kernel : BasicObject
   # variable `$?` to the process status.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   # Examples:
   #
   #     $ `date`                 # => "Wed Apr  9 08:56:30 CDT 2003\n"
   #     $ `echo oops && exit 99` # => "oops\n"
   #     $ $?                     # => #<Process::Status: pid 17088 exit 99>
-  #     $ $?.exitstatus          # => 99
+  #     $ $?.status              # => 99>
   #
   # The built-in syntax `%x{...}` uses this method.
   #
@@ -777,8 +777,6 @@ module Kernel : BasicObject
   # If *const* is defined as autoload, the file name to be loaded is replaced with
   # *filename*.  If *const* is defined but not as autoload, does nothing.
   #
-  # Files that are currently being loaded must not be registered for autoload.
-  #
   def self?.autoload: (interned _module, String filename) -> NilClass
 
   # <!--
@@ -1004,8 +1002,6 @@ module Kernel : BasicObject
   # With argument `exception` not given, argument `message` and keyword argument
   # `cause` may be given, but argument `backtrace` may not be given.
   #
-  # `cause` can not be given as an only argument.
-  #
   def self?.fail: () -> bot
                 | (string message, ?cause: Exception?) -> bot
                 | (_Exception exception, ?_ToS? message, ?String | Array[String] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> bot
@@ -1112,8 +1108,6 @@ module Kernel : BasicObject
   # With argument `exception` not given, argument `message` and keyword argument
   # `cause` may be given, but argument `backtrace` may not be given.
   #
-  # `cause` can not be given as an only argument.
-  #
   alias raise fail
 
   alias self.raise self.fail
@@ -1122,7 +1116,7 @@ module Kernel : BasicObject
   # Returns the string resulting from formatting `objects` into `format_string`.
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:language/format_specifications.rdoc).
+  # Specifications](rdoc-ref:format_specifications.rdoc).
   #
   def self?.format: (String format, *untyped args) -> String
 
@@ -1133,7 +1127,7 @@ module Kernel : BasicObject
   # Returns the string resulting from formatting `objects` into `format_string`.
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:language/format_specifications.rdoc).
+  # Specifications](rdoc-ref:format_specifications.rdoc).
   #
   alias sprintf format
 
@@ -1224,7 +1218,6 @@ module Kernel : BasicObject
   #     loop do
   #       print "Input: "
   #       line = gets
-  #       # break if q, Q is entered or EOF signal (Ctrl-D on Unix, Ctrl-Z on windows) is sent
   #       break if !line or line =~ /^q/i
   #       # ...
   #     end
@@ -1253,7 +1246,7 @@ module Kernel : BasicObject
   # Creates an IO object connected to the given file.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   # With no block given, file stream is returned:
   #
@@ -1331,7 +1324,7 @@ module Kernel : BasicObject
   #     io.write(sprintf(format_string, *objects))
   #
   # For details on `format_string`, see [Format
-  # Specifications](rdoc-ref:language/format_specifications.rdoc).
+  # Specifications](rdoc-ref:format_specifications.rdoc).
   #
   # With the single argument `format_string`, formats `objects` into the string,
   # then writes the formatted string to $stdout:
@@ -1470,9 +1463,7 @@ module Kernel : BasicObject
   # Kernel.srand may be used to ensure that sequences of random numbers are
   # reproducible between different runs of a program.
   #
-  # Related: Random.rand.
-  #     rand(100.0)        # => 64 (Integer because max.to_i is 100)
-  #     Random.rand(100.0) # => 30.315320967824523
+  # See also Random.rand.
   #
   def self?.rand: (?0) -> Float
                 | (int arg0) -> Integer
@@ -1594,8 +1585,7 @@ module Kernel : BasicObject
   # IO objects.
   #
   # Argument `timeout` is a numeric value (such as integer or float) timeout
-  # interval in seconds. `timeout` can also be `nil` or `Float::INFINITY`. `nil`
-  # and `Float::INFINITY` means no timeout.
+  # interval in seconds.
   #
   # The method monitors the IO objects given in all three arrays, waiting for some
   # to be ready; returns a 3-element array whose elements are:
@@ -1783,58 +1773,58 @@ module Kernel : BasicObject
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns `true` or `false`;
   #      for a non-existent entity, returns `false` (does not raise exception):
-  # Character|Test
-  # ---------|-------------------------------------------------------------------
-  #   `'b'`  |Whether the entity is a block device.
-  #   `'c'`  |Whether the entity is a character device.
-  #   `'d'`  |Whether the entity is a directory.
-  #   `'e'`  |Whether the entity is an existing entity.
-  #   `'f'`  |Whether the entity is an existing regular file.
-  #   `'g'`  |Whether the entity's setgid bit is set.
-  #   `'G'`  |Whether the entity's group ownership is equal to the caller's.
-  #   `'k'`  |Whether the entity's sticky bit is set.
-  #   `'l'`  |Whether the entity is a symbolic link.
-  #   `'o'`  |Whether the entity is owned by the caller's effective uid.
-  #   `'O'`  |Like `'o'`, but uses the real uid (not the effective uid).
-  #   `'p'`  |Whether the entity is a FIFO device (named pipe).
-  #   `'r'`  |Whether the entity is readable by the caller's effective uid/gid.
-  #   `'R'`  |Like `'r'`, but uses the real uid/gid (not the effective uid/gid).
-  #   `'S'`  |Whether the entity is a socket.
-  #   `'u'`  |Whether the entity's setuid bit is set.
-  #   `'w'`  |Whether the entity is writable by the caller's effective uid/gid.
-  #   `'W'`  |Like `'w'`, but uses the real uid/gid (not the effective uid/gid).
-  #   `'x'`  |Whether the entity is executable by the caller's effective uid/gid.
-  #   `'X'`  |Like `'x'`, but uses the real uid/gid (not the effective uid/git).
-  #   `'z'`  |Whether the entity exists and is of length zero.
+  #  Character  |Test
+  # ------------|-------------------------------------------------------------------------
+  # <tt>'b'</tt>|Whether the entity is a block device.
+  # <tt>'c'</tt>|Whether the entity is a character device.
+  # <tt>'d'</tt>|Whether the entity is a directory.
+  # <tt>'e'</tt>|Whether the entity is an existing entity.
+  # <tt>'f'</tt>|Whether the entity is an existing regular file.
+  # <tt>'g'</tt>|Whether the entity's setgid bit is set.
+  # <tt>'G'</tt>|Whether the entity's group ownership is equal to the caller's.
+  # <tt>'k'</tt>|Whether the entity's sticky bit is set.
+  # <tt>'l'</tt>|Whether the entity is a symbolic link.
+  # <tt>'o'</tt>|Whether the entity is owned by the caller's effective uid.
+  # <tt>'O'</tt>|Like <tt>'o'</tt>, but uses the real uid (not the effective uid).
+  # <tt>'p'</tt>|Whether the entity is a FIFO device (named pipe).
+  # <tt>'r'</tt>|Whether the entity is readable by the caller's effective uid/gid.
+  # <tt>'R'</tt>|Like <tt>'r'</tt>, but uses the real uid/gid (not the effective uid/gid).
+  # <tt>'S'</tt>|Whether the entity is a socket.
+  # <tt>'u'</tt>|Whether the entity's setuid bit is set.
+  # <tt>'w'</tt>|Whether the entity is writable by the caller's effective uid/gid.
+  # <tt>'W'</tt>|Like <tt>'w'</tt>, but uses the real uid/gid (not the effective uid/gid).
+  # <tt>'x'</tt>|Whether the entity is executable by the caller's effective uid/gid.
+  # <tt>'X'</tt>|Like <tt>'x'</tt>, but uses the real uid/gid (not the effective uid/git).
+  # <tt>'z'</tt>|Whether the entity exists and is of length zero.
   # *   This test operates only on the entity at `path0`,
   #      and returns an integer size or `nil`:
-  # Character|Test
-  # ---------|--------------------------------------------------------------------------------------------
-  #   `'s'`  |Returns positive integer size if the entity exists and has non-zero length, `nil` otherwise.
+  #  Character  |Test
+  # ------------|--------------------------------------------------------------------------------------------
+  # <tt>'s'</tt>|Returns positive integer size if the entity exists and has non-zero length, +nil+ otherwise.
   # *   Each of these tests operates only on the entity at `path0`,
   #      and returns a Time object;
   #      raises an exception if the entity does not exist:
-  # Character|Test
-  # ---------|--------------------------------------
-  #   `'A'`  |Last access time for the entity.
-  #   `'C'`  |Last change time for the entity.
-  #   `'M'`  |Last modification time for the entity.
+  #  Character  |Test
+  # ------------|--------------------------------------
+  # <tt>'A'</tt>|Last access time for the entity.
+  # <tt>'C'</tt>|Last change time for the entity.
+  # <tt>'M'</tt>|Last modification time for the entity.
   # *   Each of these tests operates on the modification time (`mtime`)
   #      of each of the entities at `path0` and `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  # Character|Test
-  # ---------|---------------------------------------------------------------
-  #   `'<'`  |Whether the `mtime` at `path0` is less than that at `path1`.
-  #   `'='`  |Whether the `mtime` at `path0` is equal to that at `path1`.
-  #   `'>'`  |Whether the `mtime` at `path0` is greater than that at `path1`.
+  #  Character  |Test
+  # ------------|---------------------------------------------------------------
+  # <tt>'<'</tt>|Whether the `mtime` at `path0` is less than that at `path1`.
+  # <tt>'='</tt>|Whether the `mtime` at `path0` is equal to that at `path1`.
+  # <tt>'>'</tt>|Whether the `mtime` at `path0` is greater than that at `path1`.
   # *   This test operates on the content of each of the entities at `path0` and
   #     `path1`,
   #      and returns a `true` or `false`;
   #      returns `false` if either entity does not exist:
-  # Character|Test
-  # ---------|---------------------------------------------
-  #   `'-'`  |Whether the entities exist and are identical.
+  #  Character  |Test
+  # ------------|---------------------------------------------
+  # <tt>'-'</tt>|Whether the entities exist and are identical.
   #
   def self?.test: (String | Integer cmd, String | IO file1, ?String | IO file2) -> (TrueClass | FalseClass | Time | nil | Integer)
 
@@ -1911,7 +1901,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   # The new process is created using the [exec system
   # call](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/e
@@ -2003,7 +1993,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   # Returns the process ID (pid) of the new process, without waiting for it to
   # complete.
@@ -2106,7 +2096,7 @@ module Kernel : BasicObject
   # *   Invoking the executable at `exe_path`.
   #
   # This method has potential security vulnerabilities if called with untrusted
-  # input; see [Command Injection](rdoc-ref:security/command_injection.rdoc).
+  # input; see [Command Injection](rdoc-ref:command_injection.rdoc).
   #
   # Returns:
   #

data/core/marshal.rbs

@@ -147,7 +147,7 @@ module Marshal
   # *   anonymous Class/Module.
   # *   objects which are related to system (ex: Dir, File::Stat, IO, File, Socket
   #     and so on)
-  # *   an instance of MatchData, Method, UnboundMethod, Proc, Thread,
+  # *   an instance of MatchData, Data, Method, UnboundMethod, Proc, Thread,
   #     ThreadGroup, Continuation
   # *   objects which define singleton methods
   #

data/core/match_data.rbs

@@ -41,7 +41,7 @@
 # *   `$'` is Regexp.last_match`.post_match`;
 # *   `$+` is Regexp.last_match`[ -1 ]` (the last capture).
 #
-# See also Regexp@Global+Variables.
+# See also "Special global variables" section in Regexp documentation.
 #
 class MatchData
   type capture = String | Symbol | int

data/core/math.rbs

@@ -410,27 +410,6 @@ module Math
   #
   def self.exp: (double x) -> Float
 
-  # <!--
-  #   rdoc-file=math.c
-  #   - Math.expm1(x) -> float
-  # -->
-  # Returns "exp(x) - 1", `e` raised to the `x` power, minus 1.
-  #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-1.0, INFINITY]`.
-  #
-  # Examples:
-  #
-  #     expm1(-INFINITY) # => 0.0
-  #     expm1(-1.0)      # => -0.6321205588285577 # 1.0/E - 1
-  #     expm1(0.0)       # => 0.0
-  #     expm1(0.5)       # => 0.6487212707001282  # sqrt(E) - 1
-  #     expm1(1.0)       # => 1.718281828459045   # E - 1
-  #     expm1(2.0)       # => 6.38905609893065    # E**2 - 1
-  #     expm1(INFINITY)  # => Infinity
-  #
-  def self.expm1: (double x) -> Float
-
   # <!--
   #   rdoc-file=math.c
   #   - Math.frexp(x) -> [fraction, exponent]
@@ -546,8 +525,9 @@ module Math
   #
   #     [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
   #
-  # See [log gamma
-  # function](https://en.wikipedia.org/wiki/Gamma_function#Log-gamma_function).
+  # See [logarithmic gamma
+  # function](https://en.wikipedia.org/wiki/Gamma_function#The_log-gamma_function)
+  # .
   #
   # *   Domain: `(-INFINITY, INFINITY]`.
   # *   Range of first element: `(-INFINITY, INFINITY]`.
@@ -623,25 +603,6 @@ module Math
   #
   def self.log10: (double x) -> Float
 
-  # <!--
-  #   rdoc-file=math.c
-  #   - Math.log1p(x) -> float
-  # -->
-  # Returns "log(x + 1)", the base E
-  # [logarithm](https://en.wikipedia.org/wiki/Logarithm) of (`x` + 1).
-  #
-  # *   Domain: `[-1, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
-  #
-  # Examples:
-  #
-  #     log1p(-1.0)     # => -Infinity
-  #     log1p(0.0)      # => 0.0
-  #     log1p(E - 1)    # => 1.0
-  #     log1p(INFINITY) # => Infinity
-  #
-  def self.log1p: (double x) -> Float
-
   # <!--
   #   rdoc-file=math.c
   #   - Math.log2(x) -> float

data/core/method.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=proc.c -->
-# `Method` objects are created by Object#method, and are associated with a
+# Method objects are created by Object#method, and are associated with a
 # particular object (not just with a class).  They may be used to invoke the
 # method within the object, and as a block associated with an iterator.  They
 # may also be unbound from one object (creating an UnboundMethod) and bound to
@@ -126,9 +126,7 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.call(args, ...) -> obj
-  #   - meth[args, ...] -> obj
-  #   - method === obj -> result_of_method
+  #   - meth.call(args, ...)    -> obj
   # -->
   # Invokes the *meth* with the specified arguments, returning the method's return
   # value.
@@ -137,32 +135,23 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
-  # Using Method#=== allows a method object to be the target of a `when` clause in
-  # a case statement.
-  #
-  #     require 'prime'
-  #
-  #     case 1373
-  #     when Prime.method(:prime?)
-  #       # ...
-  #     end
-  #
   def call: (?) -> untyped
 
   # <!--
   #   rdoc-file=proc.c
-  #   - self << g -> a_proc
+  #   - meth << g -> a_proc
   # -->
-  # Returns a proc that is the composition of the given `g` and this method.
-  #
-  # The returned proc takes a variable number of arguments. It first calls `g`
-  # with the arguments, then calls `self` with the return value of `g`.
+  # Returns a proc that is the composition of this method and the given *g*. The
+  # returned proc takes a variable number of arguments, calls *g* with them then
+  # calls this method with the result.
   #
-  #     def f(ary) = ary << 'in f'
+  #     def f(x)
+  #       x * x
+  #     end
   #
   #     f = self.method(:f)
-  #     g = proc { |ary| ary << 'in proc' }
-  #     (f << g).call([]) # => ["in proc", "in f"]
+  #     g = proc {|x| x + x }
+  #     p (f << g).call(2) #=> 16
   #
   def <<: (Proc::_Callable g) -> Proc
 
@@ -174,32 +163,23 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
-  # Using Method#=== allows a method object to be the target of a `when` clause in
-  # a case statement.
-  #
-  #     require 'prime'
-  #
-  #     case 1373
-  #     when Prime.method(:prime?)
-  #       # ...
-  #     end
-  #
   alias === call
 
   # <!--
   #   rdoc-file=proc.c
-  #   - self >> g -> a_proc
+  #   - meth >> g -> a_proc
   # -->
-  # Returns a proc that is the composition of this method and the given `g`.
-  #
-  # The returned proc takes a variable number of arguments. It first calls `self`
-  # with the arguments, then calls `g` with the return value of `self`.
+  # Returns a proc that is the composition of this method and the given *g*. The
+  # returned proc takes a variable number of arguments, calls this method with
+  # them then calls *g* with the result.
   #
-  #     def f(ary) = ary << 'in f'
+  #     def f(x)
+  #       x * x
+  #     end
   #
   #     f = self.method(:f)
-  #     g = proc { |ary| ary << 'in proc' }
-  #     (f >> g).call([]) # => ["in f", "in proc"]
+  #     g = proc {|x| x + x }
+  #     p (f >> g).call(2) #=> 8
   #
   def >>: (Proc::_Callable g) -> Proc
 
@@ -211,16 +191,6 @@ class Method
   #     m.call(3)    #=> 15
   #     m.call(20)   #=> 32
   #
-  # Using Method#=== allows a method object to be the target of a `when` clause in
-  # a case statement.
-  #
-  #     require 'prime'
-  #
-  #     case 1373
-  #     when Prime.method(:prime?)
-  #       # ...
-  #     end
-  #
   alias [] call
 
   # <!--
@@ -389,18 +359,10 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.source_location  -> [String, Integer, Integer, Integer, Integer]
+  #   - meth.source_location  -> [String, Integer]
   # -->
-  # Returns the location where the method was defined. The returned Array
-  # contains:
-  #     (1) the Ruby source filename
-  #     (2) the line number where the definition starts
-  #     (3) the column number where the definition starts
-  #     (4) the line number where the definition ends
-  #     (5) the column number where the definitions ends
-  #
-  # This method will return `nil` if the method was not defined in Ruby (i.e.
-  # native).
+  # Returns the Ruby source filename and line number containing this method or nil
+  # if this method was not defined in Ruby (i.e. native).
   #
   def source_location: () -> [String, Integer]?
 
@@ -408,8 +370,8 @@ class Method
   #   rdoc-file=proc.c
   #   - meth.super_method  -> method
   # -->
-  # Returns a `Method` of superclass which would be called when super is used or
-  # nil if there is no method on superclass.
+  # Returns a Method of superclass which would be called when super is used or nil
+  # if there is no method on superclass.
   #
   def super_method: () -> Method?
 

data/core/module.rbs

@@ -114,15 +114,12 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - self < other -> true, false, or nil
+  #   - mod < other   ->  true, false, or nil
   # -->
-  # 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
+  # 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".)
   #
   def <: (Module other) -> bool?
 
@@ -138,29 +135,14 @@ class Module < Object
 
   # <!--
   #   rdoc-file=object.c
-  #   - self <=> other -> -1, 0, 1, or nil
+  #   - module <=> other_module   -> -1, 0, +1, or nil
   # -->
-  # Compares `self` and `other`.
-  #
-  # Returns:
-  #
-  # *   `-1`, 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:
+  # 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`.
   #
-  #     # 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
+  # Returns `nil` if `module` has no relationship with `other_module`, if
+  # `other_module` is not a module, or if the two values are incomparable.
   #
   def <=>: (untyped other) -> Integer?
 
@@ -346,8 +328,6 @@ class Module < Object
   # replaced with *filename*.  If *const* is defined but not as autoload, does
   # nothing.
   #
-  # Files that are currently being loaded must not be registered for autoload.
-  #
   def autoload: (interned _module, String filename) -> NilClass
 
   # <!--
@@ -507,31 +487,6 @@ class Module < Object
   #
   #     Added :FOO
   #
-  # 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
-  #
-  # *produces:*
-  #
-  #     :const_added
-  #     :inherited
-  #
   def const_added: (Symbol) -> void
 
   # <!--
@@ -1366,52 +1321,19 @@ class Module < Object
   #   - protected(method_name, method_name, ...) -> array
   #   - protected(array)                         -> 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 `==`, 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.
-  #
-  # ## Example
-  #
-  #     class Account
-  #       # Mark balance as protected, so that we can compare between accounts
-  #       # without making it public.
-  #       attr_reader :balance
-  #       protected :balance
-  #
-  #       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
+  # 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.
   #
-  #     account1 = Account.new(100)
-  #     account2 = Account.new(50)
+  # 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.
   #
-  #     account1 > account2  # => true (works)
-  #     account1.balance     # => NoMethodError (fails because balance is not public)
+  # Note that a protected method is slow because it can't use inline cache.
   #
   # To show a private method on RDoc, use `:doc:` instead of this.
   #
@@ -1656,7 +1578,7 @@ class Module < Object
   #     m.name #=> nil
   #
   #     c = Class.new
-  #     c.set_temporary_name("MyClass(with description)") # => MyClass(with description)
+  #     c.set_temporary_name("MyClass(with description)")
   #
   #     c.new # => #<MyClass(with description):0x0....>
   #