rbs 4.0.0.dev.4 → 4.0.0

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, Data, Method, UnboundMethod, Proc, Thread,
+  # *   an instance of MatchData, Method, UnboundMethod, Proc, Thread,
   #     ThreadGroup, Continuation
   # *   objects which define singleton methods
   #
@@ -167,9 +167,9 @@ module Marshal
   # Never pass untrusted data (including user supplied input) to this method.
   # Please see the overview for further details.
   #
-  # If the `freeze: true` argument is passed, deserialized object would be deeply
-  # frozen. Note that it may lead to more efficient memory usage due to frozen
-  # strings deduplication:
+  # If the <code>freeze: true</code> argument is passed, deserialized object would
+  # be deeply frozen. Note that it may lead to more efficient memory usage due to
+  # frozen strings deduplication:
   #
   #     serialized = Marshal.dump(['value1', 'value2', 'value1', 'value2'])
   #

data/core/match_data.rbs

@@ -34,14 +34,16 @@
 # Parts of last MatchData (returned by Regexp.last_match) are also aliased as
 # global variables:
 #
-# *   `$~` is Regexp.last_match;
-# *   `$&` is Regexp.last_match`[ 0 ]`;
-# *   `$1`, `$2`, and so on are Regexp.last_match`[ i ]` (captures by number);
-# *   `$`` is Regexp.last_match`.pre_match`;
-# *   `$'` is Regexp.last_match`.post_match`;
-# *   `$+` is Regexp.last_match`[ -1 ]` (the last capture).
+# *   <code>$~</code> is Regexp.last_match;
+# *   <code>$&</code> is Regexp.last_match<code>[ 0 ]</code>;
+# *   <code>$1</code>, <code>$2</code>, and so on are Regexp.last_match<code>[ i
+#     ]</code> (captures by number);
+# *   <code>$`</code> is Regexp.last_match<code>.pre_match</code>;
+# *   <code>$'</code> is Regexp.last_match<code>.post_match</code>;
+# *   <code>$+</code> is Regexp.last_match<code>[ -1 ]</code> (the last
+#     capture).
 #
-# See also "Special global variables" section in Regexp documentation.
+# See also Regexp@Global+Variables.
 #
 class MatchData
   type capture = String | Symbol | int
@@ -230,7 +232,7 @@ class MatchData
   #   rdoc-file=re.c
   #   - captures -> array
   # -->
-  # Returns the array of captures, which are all matches except `m[0]`:
+  # Returns the array of captures, which are all matches except <code>m[0]</code>:
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
@@ -242,7 +244,7 @@ class MatchData
   def captures: () -> Array[String?]
 
   # <!-- rdoc-file=re.c -->
-  # Returns the array of captures, which are all matches except `m[0]`:
+  # Returns the array of captures, which are all matches except <code>m[0]</code>:
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
@@ -511,8 +513,8 @@ class MatchData
   #   - post_match   -> str
   # -->
   # Returns the substring of the target string from the end of the first match in
-  # `self` (that is, `self[0]`) to the end of the string; equivalent to regexp
-  # global variable `$'`:
+  # `self` (that is, <code>self[0]</code>) to the end of the string; equivalent to
+  # regexp global variable <code>$'</code>:
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
   #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
@@ -528,8 +530,8 @@ class MatchData
   #   - pre_match -> string
   # -->
   # Returns the substring of the target string from its beginning up to the first
-  # match in `self` (that is, `self[0]`); equivalent to regexp global variable
-  # `$``:
+  # match in `self` (that is, <code>self[0]</code>); equivalent to regexp global
+  # variable <code>$`</code>:
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
   #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">

data/core/math.rbs

@@ -41,8 +41,8 @@
 # because many such values are, in mathematics, of infinite precision, while in
 # numerical computation the precision is finite.
 #
-# Thus, in mathematics, *cos(π/2)* is exactly zero, but in our computation
-# `cos(PI/2)` is a number very close to zero:
+# Thus, in mathematics, <em>cos(π/2)</em> is exactly zero, but in our
+# computation <code>cos(PI/2)</code> is a number very close to zero:
 #
 #     cos(PI/2) # => 6.123031769111886e-17
 #
@@ -114,7 +114,7 @@
 #
 # #### Hypotenuse Function
 #
-# *   ::hypot: Returns `sqrt(a**2 + b**2)` for the given `a` and `b`.
+# *   ::hypot: Returns <code>sqrt(a**2 + b**2)</code> for the given `a` and `b`.
 #
 module Math
   # <!-- rdoc-file=math.c -->
@@ -137,7 +137,7 @@ module Math
   #
   #     Math.acos(42)
   #
-  # *produces:*
+  # <em>produces:</em>
   #
   #     Math::DomainError: Numerical argument is out of domain - "acos"
   #
@@ -155,8 +155,8 @@ module Math
   # Returns the [arc
   # cosine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `x`.
   #
-  # *   Domain: `[-1, 1]`.
-  # *   Range: `[0, PI]`.
+  # *   Domain: <code>[-1, 1]</code>.
+  # *   Range: <code>[0, PI]</code>.
   #
   # Examples:
   #
@@ -173,8 +173,8 @@ module Math
   # Returns the [inverse hyperbolic
   # cosine](https://en.wikipedia.org/wiki/Inverse_hyperbolic_functions) of `x`.
   #
-  # *   Domain: `[1, INFINITY]`.
-  # *   Range: `[0, INFINITY]`.
+  # *   Domain: <code>[1, INFINITY]</code>.
+  # *   Range: <code>[0, INFINITY]</code>.
   #
   # Examples:
   #
@@ -190,8 +190,8 @@ module Math
   # Returns the [arc
   # sine](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of `x`.
   #
-  # *   Domain: `[-1, -1]`.
-  # *   Range: `[-PI/2, PI/2]`.
+  # *   Domain: <code>[-1, -1]</code>.
+  # *   Range: <code>[-PI/2, PI/2]</code>.
   #
   # Examples:
   #
@@ -208,8 +208,8 @@ module Math
   # Returns the [inverse hyperbolic
   # sine](https://en.wikipedia.org/wiki/Inverse_hyperbolic_functions) of `x`.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -227,8 +227,8 @@ module Math
   # tangent](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions) of
   # `x`.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-PI/2, PI/2]  `.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-PI/2, PI/2]  </code>.
   #
   # Examples:
   #
@@ -251,9 +251,9 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain of `y`: `[-INFINITY, INFINITY]`.
-  # *   Domain of `x`: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-PI, PI]`.
+  # *   Domain of `y`: <code>[-INFINITY, INFINITY]</code>.
+  # *   Domain of `x`: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-PI, PI]</code>.
   #
   # Examples:
   #
@@ -271,8 +271,8 @@ module Math
   # Returns the [inverse hyperbolic
   # tangent](https://en.wikipedia.org/wiki/Inverse_hyperbolic_functions) of `x`.
   #
-  # *   Domain: `[-1, 1]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[-1, 1]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -288,8 +288,8 @@ module Math
   # -->
   # Returns the [cube root](https://en.wikipedia.org/wiki/Cube_root) of `x`.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -315,8 +315,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `(-INFINITY, INFINITY)`.
-  # *   Range: `[-1.0, 1.0]`.
+  # *   Domain: <code>(-INFINITY, INFINITY)</code>.
+  # *   Range: <code>[-1.0, 1.0]</code>.
   #
   # Examples:
   #
@@ -337,8 +337,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[1, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[1, INFINITY]</code>.
   #
   # Examples:
   #
@@ -355,8 +355,8 @@ module Math
   # Returns the value of the [Gauss error
   # function](https://en.wikipedia.org/wiki/Error_function) for `x`.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-1, 1]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-1, 1]</code>.
   #
   # Examples:
   #
@@ -376,8 +376,8 @@ module Math
   # function](https://en.wikipedia.org/wiki/Error_function#Complementary_error_fun
   # ction) for `x`.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[0, 2]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[0, 2]</code>.
   #
   # Examples:
   #
@@ -395,8 +395,8 @@ module Math
   # -->
   # Returns `e` raised to the `x` power.
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[0, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[0, INFINITY]</code>.
   #
   # Examples:
   #
@@ -410,6 +410,27 @@ 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: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-1.0, INFINITY]</code>.
+  #
+  # 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]
@@ -423,8 +444,8 @@ module Math
   # binary64](https://en.wikipedia.org/wiki/Double-precision_floating-point_format
   # #IEEE_754_double-precision_binary_floating-point_format:_binary64).
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -447,8 +468,8 @@ module Math
   # Returns the value of the [gamma
   # function](https://en.wikipedia.org/wiki/Gamma_function) for `x`.
   #
-  # *   Domain: `(-INFINITY, INFINITY]` excluding negative integers.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>(-INFINITY, INFINITY]</code> excluding negative integers.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -470,12 +491,13 @@ module Math
   #   rdoc-file=math.c
   #   - Math.hypot(a, b) -> float
   # -->
-  # Returns `sqrt(a**2 + b**2)`, which is the length of the longest side `c` (the
-  # hypotenuse) of the right triangle whose other sides have lengths `a` and `b`.
+  # Returns <code>sqrt(a**2 + b**2)</code>, which is the length of the longest
+  # side `c` (the hypotenuse) of the right triangle whose other sides have lengths
+  # `a` and `b`.
   #
-  # *   Domain of `a`: `[-INFINITY, INFINITY]`.
-  # *   Domain of +ab: `[-INFINITY, INFINITY]`.
-  # *   Range: `[0, INFINITY]`.
+  # *   Domain of `a`: <code>[-INFINITY, INFINITY]</code>.
+  # *   Domain of +ab: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[0, INFINITY]</code>.
   #
   # Examples:
   #
@@ -485,8 +507,8 @@ module Math
   #     hypot(5.0, 12.0)      # => 13.0
   #     hypot(1.0, sqrt(3.0)) # => 1.9999999999999998 # Near 2.0
   #
-  # Note that if either argument is `INFINITY` or `-INFINITY`, the result is
-  # `Infinity`.
+  # Note that if either argument is `INFINITY` or <code>-INFINITY</code>, the
+  # result is `Infinity`.
   #
   def self.hypot: (double x, double y) -> Float
 
@@ -494,10 +516,11 @@ module Math
   #   rdoc-file=math.c
   #   - Math.ldexp(fraction, exponent) -> float
   # -->
-  # Returns the value of `fraction * 2**exponent`.
+  # Returns the value of <code>fraction * 2**exponent</code>.
   #
-  # *   Domain of `fraction`: `[0.0, 1.0)`.
-  # *   Domain of `exponent`: `[0, 1024]` (larger values are equivalent to 1024).
+  # *   Domain of `fraction`: <code>[0.0, 1.0)</code>.
+  # *   Domain of `exponent`: <code>[0, 1024]</code> (larger values are equivalent
+  #     to 1024).
   #
   # See [IEEE 754 double-precision binary floating-point format:
   # binary64](https://en.wikipedia.org/wiki/Double-precision_floating-point_format
@@ -525,12 +548,11 @@ module Math
   #
   #     [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
   #
-  # See [logarithmic gamma
-  # function](https://en.wikipedia.org/wiki/Gamma_function#The_log-gamma_function)
-  # .
+  # See [log gamma
+  # function](https://en.wikipedia.org/wiki/Gamma_function#Log-gamma_function).
   #
-  # *   Domain: `(-INFINITY, INFINITY]`.
-  # *   Range of first element: `(-INFINITY, INFINITY]`.
+  # *   Domain: <code>(-INFINITY, INFINITY]</code>.
+  # *   Range of first element: <code>(-INFINITY, INFINITY]</code>.
   # *   Second element is -1 or 1.
   #
   # Examples:
@@ -564,8 +586,8 @@ module Math
   # Returns the base `base` [logarithm](https://en.wikipedia.org/wiki/Logarithm)
   # of `x`.
   #
-  # *   Domain: `[0, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY)]`.
+  # *   Domain: <code>[0, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY)]</code>.
   #
   # Examples:
   #
@@ -591,8 +613,8 @@ module Math
   # Returns the base 10 [logarithm](https://en.wikipedia.org/wiki/Logarithm) of
   # `x`.
   #
-  # *   Domain: `[0, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[0, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -603,6 +625,25 @@ 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: <code>[-1, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
+  #
+  # 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
@@ -610,8 +651,8 @@ module Math
   # Returns the base 2 [logarithm](https://en.wikipedia.org/wiki/Logarithm) of
   # `x`.
   #
-  # *   Domain: `[0, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[0, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -630,8 +671,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `(-INFINITY, INFINITY)`.
-  # *   Range: `[-1.0, 1.0]`.
+  # *   Domain: <code>(-INFINITY, INFINITY)</code>.
+  # *   Range: <code>[-1.0, 1.0]</code>.
   #
   # Examples:
   #
@@ -652,8 +693,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-INFINITY, INFINITY]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-INFINITY, INFINITY]</code>.
   #
   # Examples:
   #
@@ -670,8 +711,8 @@ module Math
   # Returns the principal (non-negative) [square
   # root](https://en.wikipedia.org/wiki/Square_root) of `x`.
   #
-  # *   Domain: `[0, INFINITY]`.
-  # *   Range: `[0, INFINITY]`.
+  # *   Domain: <code>[0, INFINITY]</code>.
+  # *   Range: <code>[0, INFINITY]</code>.
   #
   # Examples:
   #
@@ -694,8 +735,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `(-INFINITY, INFINITY)`.
-  # *   Range: `(-INFINITY, INFINITY)`.
+  # *   Domain: <code>(-INFINITY, INFINITY)</code>.
+  # *   Range: <code>(-INFINITY, INFINITY)</code>.
   #
   # Examples:
   #
@@ -716,8 +757,8 @@ module Math
   # [radians](https://en.wikipedia.org/wiki/Trigonometric_functions#Radians_versus
   # _degrees).
   #
-  # *   Domain: `[-INFINITY, INFINITY]`.
-  # *   Range: `[-1, 1]`.
+  # *   Domain: <code>[-INFINITY, INFINITY]</code>.
+  # *   Range: <code>[-1, 1]</code>.
   #
   # Examples:
   #

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
@@ -54,8 +54,6 @@ class Method
   #
   def hash: () -> Integer
 
-  def dup: () -> self
-
   # <!--
   #   rdoc-file=proc.c
   #   - meth.to_s      ->  string
@@ -76,12 +74,12 @@ class Method
   #     Net::HTTP.method(:get).inspect
   #     #=> "#<Method: Net::HTTP.get(uri_or_host, path=..., port=...) <skip>/lib/ruby/2.7.0/net/http.rb:457>"
   #
-  # `...` in argument definition means argument is optional (has some default
-  # value).
+  # <code>...</code> in argument definition means argument is optional (has some
+  # default value).
   #
   # For methods defined in C (language core and extensions), location and argument
   # names can't be extracted, and only generic information is provided in form of
-  # `*` (any number of arguments) or `_` (some positional argument).
+  # <code>*</code> (any number of arguments) or `_` (some positional argument).
   #
   #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
   #     "cat".method(:+).inspect       #=> "#<Method: String#+(_)>""
@@ -104,12 +102,12 @@ class Method
   #     Net::HTTP.method(:get).inspect
   #     #=> "#<Method: Net::HTTP.get(uri_or_host, path=..., port=...) <skip>/lib/ruby/2.7.0/net/http.rb:457>"
   #
-  # `...` in argument definition means argument is optional (has some default
-  # value).
+  # <code>...</code> in argument definition means argument is optional (has some
+  # default value).
   #
   # For methods defined in C (language core and extensions), location and argument
   # names can't be extracted, and only generic information is provided in form of
-  # `*` (any number of arguments) or `_` (some positional argument).
+  # <code>*</code> (any number of arguments) or `_` (some positional argument).
   #
   #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
   #     "cat".method(:+).inspect       #=> "#<Method: String#+(_)>""
@@ -126,7 +124,9 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.call(args, ...)    -> obj
+  #   - meth.call(args, ...) -> obj
+  #   - meth[args, ...] -> obj
+  #   - method === obj -> result_of_method
   # -->
   # Invokes the *meth* with the specified arguments, returning the method's return
   # value.
@@ -135,23 +135,32 @@ 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
-  #   - meth << g -> a_proc
+  #   - self << 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, calls *g* with them then
-  # calls this method with the result.
+  # Returns a proc that is the composition of the given `g` and this method.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # 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`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f << g).call(2) #=> 16
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f << g).call([]) # => ["in proc", "in f"]
   #
   def <<: (Proc::_Callable g) -> Proc
 
@@ -163,23 +172,32 @@ 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
-  #   - meth >> g -> a_proc
+  #   - self >> 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, calls this method with
-  # them then calls *g* with the result.
+  # Returns a proc that is the composition of this method and the given `g`.
   #
-  #     def f(x)
-  #       x * x
-  #     end
+  # 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`.
+  #
+  #     def f(ary) = ary << 'in f'
   #
   #     f = self.method(:f)
-  #     g = proc {|x| x + x }
-  #     p (f >> g).call(2) #=> 8
+  #     g = proc { |ary| ary << 'in proc' }
+  #     (f >> g).call([]) # => ["in f", "in proc"]
   #
   def >>: (Proc::_Callable g) -> Proc
 
@@ -191,6 +209,16 @@ 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
 
   # <!--
@@ -359,10 +387,18 @@ class Method
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.source_location  -> [String, Integer]
+  #   - meth.source_location  -> [String, Integer, Integer, Integer, Integer]
   # -->
-  # Returns the Ruby source filename and line number containing this method or nil
-  # if this method was not defined in Ruby (i.e. native).
+  # 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).
   #
   def source_location: () -> [String, Integer]?
 
@@ -370,8 +406,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?