rbs 2.8.4 → 3.8.1

data/core/numeric.rbs

@@ -74,168 +74,88 @@
 #
 # First, what's elsewhere. Class Numeric:
 #
-# *   Inherits from [class
-#     Object](Object.html#class-Object-label-What-27s+Here).
-# *   Includes [module
-#     Comparable](Comparable.html#module-Comparable-label-What-27s+Here).
-#
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
 # Here, class Numeric provides methods for:
 #
-# *   [Querying](#class-Numeric-label-Querying)
-# *   [Comparing](#class-Numeric-label-Comparing)
-# *   [Converting](#class-Numeric-label-Converting)
-# *   [Other](#class-Numeric-label-Other)
-#
+# *   [Querying](rdoc-ref:Numeric@Querying)
+# *   [Comparing](rdoc-ref:Numeric@Comparing)
+# *   [Converting](rdoc-ref:Numeric@Converting)
+# *   [Other](rdoc-ref:Numeric@Other)
 #
 # ### Querying
 #
-#     #finite?
-# :       Returns true unless `self` is infinite or not a number.
-#
-#     #infinite?
-# :       Returns -1, `nil` or +1, depending on whether `self` is
-#         `-Infinity<tt>, finite, or <tt>+Infinity`.
-#
-#     #integer?
-# :       Returns whether `self` is an integer.
-#
-#     #negative?
-# :       Returns whether `self` is negative.
-#
-#     #nonzero?
-# :       Returns whether `self` is not zero.
-#
-#     #positive?
-# :       Returns whether `self` is positive.
-#
-#     #real?
-# :       Returns whether `self` is a real value.
-#
-#     #zero?
-# :       Returns whether `self` is zero.
-#
-#
+# *   #finite?: Returns true unless `self` is infinite or not a number.
+# *   #infinite?: Returns -1, `nil` or +1, depending on whether `self` is
+#     `-Infinity<tt>, finite, or <tt>+Infinity`.
+# *   #integer?: Returns whether `self` is an integer.
+# *   #negative?: Returns whether `self` is negative.
+# *   #nonzero?: Returns whether `self` is not zero.
+# *   #positive?: Returns whether `self` is positive.
+# *   #real?: Returns whether `self` is a real value.
+# *   #zero?: Returns whether `self` is zero.
 #
 # ### Comparing
 #
-#     [<=>](#method-i-3C-3D-3E)
-# :       Returns:
+# *   #<=>: Returns:
 #
 #     *   -1 if  `self` is less than the given value.
 #     *   0 if `self` is equal to the given value.
 #     *   1 if `self` is greater than the given value.
 #     *   `nil` if `self` and the given value are not comparable.
 #
-#     #eql?
-# :       Returns whether `self` and the given value have the same value and
-#         type.
-#
-#
+# *   #eql?: Returns whether `self` and the given value have the same value and
+#     type.
 #
 # ### Converting
 #
-#     #% (aliased as #modulo)
-# :       Returns the remainder of `self` divided by the given value.
-#
-#     #-@
-# :       Returns the value of `self`, negated.
-#
-#     #abs (aliased as #magnitude)
-# :       Returns the absolute value of `self`.
-#
-#     #abs2
-# :       Returns the square of `self`.
-#
-#     #angle (aliased as #arg and #phase)
-# :       Returns 0 if `self` is positive, Math::PI otherwise.
-#
-#     #ceil
-# :       Returns the smallest number greater than or equal to `self`, to a
-#         given precision.
-#
-#     #coerce
-# :       Returns array `[coerced_self, coerced_other]` for the given other
-#         value.
-#
-#     #conj (aliased as #conjugate)
-# :       Returns the complex conjugate of `self`.
-#
-#     #denominator
-# :       Returns the denominator (always positive) of the Rational
-#         representation of `self`.
-#
-#     #div
-# :       Returns the value of `self` divided by the given value and converted
-#         to an integer.
-#
-#     #divmod
-# :       Returns array `[quotient, modulus]` resulting from dividing `self` the
-#         given divisor.
-#
-#     #fdiv
-# :       Returns the Float result of dividing `self` by the given divisor.
-#
-#     #floor
-# :       Returns the largest number less than or equal to `self`, to a given
-#         precision.
-#
-#     #i
-# :       Returns the Complex object `Complex(0, self)`. the given value.
-#
-#     #imaginary (aliased as #imag)
-# :       Returns the imaginary part of the `self`.
-#
-#     #numerator
-# :       Returns the numerator of the Rational representation of `self`; has
-#         the same sign as `self`.
-#
-#     #polar
-# :       Returns the array `[self.abs, self.arg]`.
-#
-#     #quo
-# :       Returns the value of `self` divided by the given value.
-#
-#     #real
-# :       Returns the real part of `self`.
-#
-#     #rect (aliased as #rectangular)
-# :       Returns the array `[self, 0]`.
-#
-#     #remainder
-# :       Returns `self-arg*(self/arg).truncate` for the given `arg`.
-#
-#     #round
-# :       Returns the value of `self` rounded to the nearest value for the given
-#         a precision.
-#
-#     #to_c
-# :       Returns the Complex representation of `self`.
-#
-#     #to_int
-# :       Returns the Integer representation of `self`, truncating if necessary.
-#
-#     #truncate
-# :       Returns `self` truncated (toward zero) to a given precision.
-#
-#
+# *   #% (aliased as #modulo): Returns the remainder of `self` divided by the
+#     given value.
+# *   #-@: Returns the value of `self`, negated.
+# *   #abs (aliased as #magnitude): Returns the absolute value of `self`.
+# *   #abs2: Returns the square of `self`.
+# *   #angle (aliased as #arg and #phase): Returns 0 if `self` is positive,
+#     Math::PI otherwise.
+# *   #ceil: Returns the smallest number greater than or equal to `self`, to a
+#     given precision.
+# *   #coerce: Returns array `[coerced_self, coerced_other]` for the given other
+#     value.
+# *   #conj (aliased as #conjugate): Returns the complex conjugate of `self`.
+# *   #denominator: Returns the denominator (always positive) of the Rational
+#     representation of `self`.
+# *   #div: Returns the value of `self` divided by the given value and converted
+#     to an integer.
+# *   #divmod: Returns array `[quotient, modulus]` resulting from dividing
+#     `self` the given divisor.
+# *   #fdiv: Returns the Float result of dividing `self` by the given divisor.
+# *   #floor: Returns the largest number less than or equal to `self`, to a
+#     given precision.
+# *   #i: Returns the Complex object `Complex(0, self)`. the given value.
+# *   #imaginary (aliased as #imag): Returns the imaginary part of the `self`.
+# *   #numerator: Returns the numerator of the Rational representation of
+#     `self`; has the same sign as `self`.
+# *   #polar: Returns the array `[self.abs, self.arg]`.
+# *   #quo: Returns the value of `self` divided by the given value.
+# *   #real: Returns the real part of `self`.
+# *   #rect (aliased as #rectangular): Returns the array `[self, 0]`.
+# *   #remainder: Returns `self-arg*(self/arg).truncate` for the given `arg`.
+# *   #round: Returns the value of `self` rounded to the nearest value for the
+#     given a precision.
+# *   #to_c: Returns the Complex representation of `self`.
+# *   #to_int: Returns the Integer representation of `self`, truncating if
+#     necessary.
+# *   #truncate: Returns `self` truncated (toward zero) to a given precision.
 #
 # ### Other
 #
-#     #clone
-# :       Returns `self`; does not allow freezing.
-#
-#     #dup (aliased as #+@)
-# :       Returns `self`.
-#
-#     #step
-# :       Invokes the given block with the sequence of specified numbers.
+# *   #clone: Returns `self`; does not allow freezing.
+# *   #dup (aliased as #+@): Returns `self`.
+# *   #step: Invokes the given block with the sequence of specified numbers.
 #
 class Numeric
   include Comparable
 
-  public
-
   # <!--
   #   rdoc-file=numeric.c
   #   - self % other -> real_numeric
@@ -247,9 +167,9 @@ class Numeric
   #
   # For Rational `r` and real number `n`, these expressions are equivalent:
   #
-  #     c % n
-  #     c-n*(c/n).floor
-  #     c.divmod(n)[1]
+  #     r % n
+  #     r-n*(r/n).floor
+  #     r.divmod(n)[1]
   #
   # See Numeric#divmod.
   #
@@ -268,8 +188,6 @@ class Numeric
   #     (-r) % r2             # => (119/100)
   #     (-r) %-r2             # => (-21/100)
   #
-  # Numeric#modulo is an alias for Numeric#%.
-  #
   def %: (Numeric) -> Numeric
 
   # Performs addition: the class of the resulting object depends on the class of
@@ -278,7 +196,7 @@ class Numeric
   def +: (Numeric) -> Numeric
 
   # <!--
-  #   rdoc-file=numeric.c
+  #   rdoc-file=numeric.rb
   #   - +self -> self
   # -->
   # Returns `self`.
@@ -318,42 +236,40 @@ class Numeric
   #     (-34.56).abs  #=> 34.56
   #     -34.56.abs    #=> 34.56
   #
-  # Numeric#magnitude is an alias for Numeric#abs.
-  #
   def abs: () -> Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - num.abs2  ->  real
+  #   - abs2 -> real
   # -->
-  # Returns square of self.
+  # Returns the square of `self`.
   #
   def abs2: () -> Numeric
 
   # <!-- rdoc-file=complex.c -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns zero if `self` is positive, Math::PI otherwise.
   #
   def angle: () -> Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - num.arg    ->  0 or float
-  #   - num.angle  ->  0 or float
-  #   - num.phase  ->  0 or float
+  #   - arg -> 0 or Math::PI
   # -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns zero if `self` is positive, Math::PI otherwise.
   #
   alias arg angle
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - ceil(digits = 0) -> integer or float
+  #   - ceil(ndigits = 0) -> float or integer
   # -->
-  # Returns the smallest number that is greater than or equal to `self` with a
-  # precision of `digits` decimal digits.
+  # Returns the smallest float or integer that is greater than or equal to `self`,
+  # as specified by the given `ndigits`, which must be an [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Numeric implements this by converting `self` to a Float and invoking
-  # Float#ceil.
+  # Equivalent to `self.to_f.ceil(ndigits)`.
+  #
+  # Related: #floor, Float#ceil.
   #
   def ceil: () -> Integer
           | (Integer digits) -> (Integer | Numeric)
@@ -392,17 +308,18 @@ class Numeric
   #
   def coerce: (Numeric) -> [ Numeric, Numeric ]
 
-  # <!-- rdoc-file=complex.c -->
-  # Returns self.
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - conj()
+  # -->
   #
   def conj: () -> Numeric
 
   # <!--
-  #   rdoc-file=complex.c
-  #   - num.conj       ->  self
-  #   - num.conjugate  ->  self
+  #   rdoc-file=numeric.rb
+  #   - conj -> self
   # -->
-  # Returns self.
+  # Returns `self`.
   #
   def conjugate: () -> Numeric
 
@@ -422,8 +339,8 @@ class Numeric
   # `/` in the derived class of `self`. (Numeric itself does not define method
   # `/`.)
   #
-  # Of the Core and Standard Library classes, Float, Rational, and Complex use
-  # this implementation.
+  # Of the Core and Standard Library classes, Only Float and Rational use this
+  # implementation.
   #
   def div: (Numeric) -> Integer
 
@@ -472,8 +389,8 @@ class Numeric
   #     1.eql?(Rational(1, 1)) # => false
   #     1.eql?(Complex(1, 0))  # => false
   #
-  # Method `eql?` is different from +==+ in that `eql?` requires matching types,
-  # while +==+ does not.
+  # Method `eql?` is different from `==` in that `eql?` requires matching types,
+  # while `==` does not.
   #
   def eql?: (untyped) -> bool
 
@@ -491,21 +408,23 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - num.finite?  ->  true or false
+  #   - finite? -> true or false
   # -->
-  # Returns `true` if `num` is a finite number, otherwise returns `false`.
+  # Returns `true` if `self` is a finite number, `false` otherwise.
   #
   def finite?: () -> bool
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - floor(digits = 0) -> integer or float
+  #   - floor(ndigits = 0) -> float or integer
   # -->
-  # Returns the largest number that is less than or equal to `self` with a
-  # precision of `digits` decimal digits.
+  # Returns the largest float or integer that is less than or equal to `self`, as
+  # specified by the given `ndigits`, which must be an [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
   #
-  # Numeric implements this by converting `self` to a Float and invoking
-  # Float#floor.
+  # Equivalent to `self.to_f.floor(ndigits)`.
+  #
+  # Related: #ceil, Float#floor.
   #
   def floor: () -> Integer
            | (Integer digits) -> Numeric
@@ -524,15 +443,16 @@ class Numeric
   #
   def i: () -> Complex
 
-  # <!-- rdoc-file=complex.c -->
-  # Returns zero.
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - imag()
+  # -->
   #
   def imag: () -> Numeric
 
   # <!--
-  #   rdoc-file=complex.c
-  #   - num.imag       ->  0
-  #   - num.imaginary  ->  0
+  #   rdoc-file=numeric.rb
+  #   - imag -> 0
   # -->
   # Returns zero.
   #
@@ -540,21 +460,21 @@ class Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - num.infinite?  ->  -1, 1, or nil
+  #   - infinite? -> -1, 1, or nil
   # -->
-  # Returns `nil`, -1, or 1 depending on whether the value is finite, `-Infinity`,
-  # or `+Infinity`.
+  # Returns `nil`, -1, or 1 depending on whether `self` is finite, `-Infinity`, or
+  # `+Infinity`.
   #
   def infinite?: () -> Integer?
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - num.integer?  ->  true or false
+  #   - integer? -> true or false
   # -->
-  # Returns `true` if `num` is an Integer.
+  # Returns `true` if `self` is an Integer.
   #
-  #     1.0.integer?   #=> false
-  #     1.integer?     #=> true
+  #     1.0.integer? # => false
+  #     1.integer?   # => true
   #
   def integer?: () -> bool
 
@@ -565,8 +485,6 @@ class Numeric
   #     (-34.56).abs  #=> 34.56
   #     -34.56.abs    #=> 34.56
   #
-  # Numeric#magnitude is an alias for Numeric#abs.
-  #
   alias magnitude abs
 
   # <!-- rdoc-file=numeric.c -->
@@ -577,9 +495,9 @@ class Numeric
   #
   # For Rational `r` and real number `n`, these expressions are equivalent:
   #
-  #     c % n
-  #     c-n*(c/n).floor
-  #     c.divmod(n)[1]
+  #     r % n
+  #     r-n*(r/n).floor
+  #     r.divmod(n)[1]
   #
   # See Numeric#divmod.
   #
@@ -598,8 +516,6 @@ class Numeric
   #     (-r) % r2             # => (119/100)
   #     (-r) %-r2             # => (-21/100)
   #
-  # Numeric#modulo is an alias for Numeric#%.
-  #
   def modulo: (Numeric) -> Numeric
 
   # <!--
@@ -614,17 +530,19 @@ class Numeric
   #   rdoc-file=numeric.c
   #   - nonzero?  ->  self or nil
   # -->
-  # Returns `self` if `self` is not a zero value, `nil` otherwise; uses method
-  # `zero?` for the evaluation.
+  # Returns +self+ if +self+ is not a zero value, +nil+ otherwise;
+  #     uses method <tt>zero?</tt> for the evaluation.
+  #
+  #     The returned +self+ allows the method to be chained:
   #
-  # The returned `self` allows the method to be chained:
+  #       a = %w[z Bb bB bb BB a aA Aa AA A]
+  #       a.sort {|a, b| (a.downcase <=> b.downcase).nonzero? || a <=> b }
+  #       # => ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
   #
-  #     a = %w[z Bb bB bb BB a aA Aa AA A]
-  #     a.sort {|a, b| (a.downcase <=> b.downcase).nonzero? || a <=> b }
-  #     # => ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"]
+  #     Of the Core and Standard Library classes,
+  #     Integer, Float, Rational, and Complex use this implementation.
   #
-  # Of the Core and Standard Library classes, Integer, Float, Rational, and
-  # Complex use this implementation.
+  # Related: #zero?
   #
   def nonzero?: () -> self?
 
@@ -637,15 +555,15 @@ class Numeric
   def numerator: () -> Numeric
 
   # <!-- rdoc-file=complex.c -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns zero if `self` is positive, Math::PI otherwise.
   #
   alias phase angle
 
   # <!--
   #   rdoc-file=complex.c
-  #   - num.polar  ->  array
+  #   - polar -> array
   # -->
-  # Returns an array; [num.abs, num.arg].
+  # Returns array `[self.abs, self.arg]`.
   #
   def polar: () -> [ Numeric, Numeric ]
 
@@ -667,32 +585,31 @@ class Numeric
   def quo: (Numeric) -> Numeric
 
   # <!--
-  #   rdoc-file=complex.c
-  #   - num.real  ->  self
+  #   rdoc-file=numeric.rb
+  #   - real -> self
   # -->
-  # Returns self.
+  # Returns `self`.
   #
   def real: () -> Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - num.real?  ->  true or false
+  #   - real? -> true or false
   # -->
-  # Returns `true` if `num` is a real number (i.e. not Complex).
+  # Returns `true` if `self` is a real number (i.e. not Complex).
   #
   def real?: () -> bool
 
   # <!-- rdoc-file=complex.c -->
-  # Returns an array; [num, 0].
+  # Returns array `[self, 0]`.
   #
   def rect: () -> [ Numeric, Numeric ]
 
   # <!--
   #   rdoc-file=complex.c
-  #   - num.rect  ->  array
-  #   - num.rectangular  ->  array
+  #   - rect -> array
   # -->
-  # Returns an array; [num, 0].
+  # Returns array `[self, 0]`.
   #
   alias rectangular rect
 
@@ -753,86 +670,83 @@ class Numeric
   # -->
   # Generates a sequence of numbers; with a block given, traverses the sequence.
   #
-  #     Of the Core and Standard Library classes,
-  #     Integer, Float, and Rational use this implementation.
-  #
-  #     A quick example:
-  #
-  #       squares = []
-  #       1.step(by: 2, to: 10) {|i| squares.push(i*i) }
-  #       squares # => [1, 9, 25, 49, 81]
-  #
-  #     The generated sequence:
-  #
-  #     - Begins with +self+.
-  #     - Continues at intervals of +step+ (which may not be zero).
-  #     - Ends with the last number that is within or equal to +limit+;
-  #       that is, less than or equal to +limit+ if +step+ is positive,
-  #       greater than or equal to +limit+ if +step+ is negative.
-  #       If +limit+ is not given, the sequence is of infinite length.
-  #
-  #     If a block is given, calls the block with each number in the sequence;
-  #     returns +self+.  If no block is given, returns an Enumerator::ArithmeticSequence.
-  #
-  #     <b>Keyword Arguments</b>
-  #
-  #     With keyword arguments +by+ and +to+,
-  #     their values (or defaults) determine the step and limit:
-  #
-  #       # Both keywords given.
-  #       squares = []
-  #       4.step(by: 2, to: 10) {|i| squares.push(i*i) }    # => 4
-  #       squares # => [16, 36, 64, 100]
-  #       cubes = []
-  #       3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3
-  #       cubes   # => [27.0, 3.375, 0.0, -3.375, -27.0]
-  #       squares = []
-  #       1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) }
-  #       squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
-  #
-  #       squares = []
-  #       Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) }
-  #       squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
-  #
-  #       # Only keyword to given.
-  #       squares = []
-  #       4.step(to: 10) {|i| squares.push(i*i) }           # => 4
-  #       squares # => [16, 25, 36, 49, 64, 81, 100]
-  #       # Only by given.
-  #
-  #       # Only keyword by given
-  #       squares = []
-  #       4.step(by:2) {|i| squares.push(i*i); break if i > 10 }
-  #       squares # => [16, 36, 64, 100, 144]
-  #
-  #       # No block given.
-  #       e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3))
-  #       e.class                      # => Enumerator::ArithmeticSequence
-  #
-  #     <b>Positional Arguments</b>
-  #
-  #     With optional positional arguments +limit+ and +step+,
-  #     their values (or defaults) determine the step and limit:
-  #
-  #       squares = []
-  #       4.step(10, 2) {|i| squares.push(i*i) }    # => 4
-  #       squares # => [16, 36, 64, 100]
-  #       squares = []
-  #       4.step(10) {|i| squares.push(i*i) }
-  #       squares # => [16, 25, 36, 49, 64, 81, 100]
-  #       squares = []
-  #       4.step {|i| squares.push(i*i); break if i > 10 }  # => nil
-  #       squares # => [16, 25, 36, 49, 64, 81, 100, 121]
+  # Of the Core and Standard Library classes, Integer, Float, and Rational use
+  # this implementation.
+  #
+  # A quick example:
+  #
+  #     squares = []
+  #     1.step(by: 2, to: 10) {|i| squares.push(i*i) }
+  #     squares # => [1, 9, 25, 49, 81]
+  #
+  # The generated sequence:
+  #
+  # *   Begins with `self`.
+  # *   Continues at intervals of `by` (which may not be zero).
+  # *   Ends with the last number that is within or equal to `to`; that is, less
+  #     than or equal to `to` if `by` is positive, greater than or equal to `to`
+  #     if `by` is negative. If `to` is `nil`, the sequence is of infinite length.
+  #
+  # If a block is given, calls the block with each number in the sequence; returns
+  # `self`. If no block is given, returns an Enumerator::ArithmeticSequence.
+  #
+  # **Keyword Arguments**
+  #
+  # With keyword arguments `by` and `to`, their values (or defaults) determine the
+  # step and limit:
+  #
+  #     # Both keywords given.
+  #     squares = []
+  #     4.step(by: 2, to: 10) {|i| squares.push(i*i) }    # => 4
+  #     squares # => [16, 36, 64, 100]
+  #     cubes = []
+  #     3.step(by: -1.5, to: -3) {|i| cubes.push(i*i*i) } # => 3
+  #     cubes   # => [27.0, 3.375, 0.0, -3.375, -27.0]
+  #     squares = []
+  #     1.2.step(by: 0.2, to: 2.0) {|f| squares.push(f*f) }
+  #     squares # => [1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
+  #
+  #     squares = []
+  #     Rational(6/5).step(by: 0.2, to: 2.0) {|r| squares.push(r*r) }
+  #     squares # => [1.0, 1.44, 1.9599999999999997, 2.5600000000000005, 3.24, 4.0]
+  #
+  #     # Only keyword to given.
+  #     squares = []
+  #     4.step(to: 10) {|i| squares.push(i*i) }           # => 4
+  #     squares # => [16, 25, 36, 49, 64, 81, 100]
+  #     # Only by given.
+  #
+  #     # Only keyword by given
+  #     squares = []
+  #     4.step(by:2) {|i| squares.push(i*i); break if i > 10 }
+  #     squares # => [16, 36, 64, 100, 144]
+  #
+  #     # No block given.
+  #     e = 3.step(by: -1.5, to: -3) # => (3.step(by: -1.5, to: -3))
+  #     e.class                      # => Enumerator::ArithmeticSequence
+  #
+  # **Positional Arguments**
+  #
+  # With optional positional arguments `to` and `by`, their values (or defaults)
+  # determine the step and limit:
+  #
+  #     squares = []
+  #     4.step(10, 2) {|i| squares.push(i*i) }    # => 4
+  #     squares # => [16, 36, 64, 100]
+  #     squares = []
+  #     4.step(10) {|i| squares.push(i*i) }
+  #     squares # => [16, 25, 36, 49, 64, 81, 100]
+  #     squares = []
+  #     4.step {|i| squares.push(i*i); break if i > 10 }  # => nil
+  #     squares # => [16, 25, 36, 49, 64, 81, 100, 121]
   #
   # **Implementation Notes**
   #
-  #     If all the arguments are integers, the loop operates using an integer
-  #     counter.
+  # If all the arguments are integers, the loop operates using an integer counter.
   #
-  #     If any of the arguments are floating point numbers, all are converted
-  #     to floats, and the loop is executed
-  #     <i>floor(n + n*Float::EPSILON) + 1</i> times,
-  #     where <i>n = (limit - self)/step</i>.
+  # If any of the arguments are floating point numbers, all are converted to
+  # floats, and the loop is executed *floor(n + n*Float::EPSILON) + 1* times,
+  # where *n = (limit - self)/step*.
   #
   def step: (?Numeric limit, ?Numeric step) { (Numeric) -> void } -> self
           | (?Numeric limit, ?Numeric step) -> Enumerator[Numeric, self]
@@ -841,9 +755,9 @@ class Numeric
 
   # <!--
   #   rdoc-file=complex.c
-  #   - num.to_c  ->  complex
+  #   - to_c -> complex
   # -->
-  # Returns the value as a complex.
+  # Returns `self` as a Complex object.
   #
   def to_c: () -> Complex
 
@@ -862,7 +776,7 @@ class Numeric
   #     Rational(1, 2).to_int # => 0
   #     Rational(2, 1).to_int # => 2
   #     Complex(2, 0).to_int  # => 2
-  #     Complex(2, 1)         # Raises RangeError (non-zero imaginary part)
+  #     Complex(2, 1).to_int  # Raises RangeError (non-zero imaginary part)
   #
   def to_int: () -> Integer