rbs 2.0.0 → 2.1.0

data/stdlib/bigdecimal/0/big_decimal.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # BigDecimal provides arbitrary-precision floating point decimal arithmetic.
 #
 # ## Introduction
@@ -40,6 +41,19 @@
 #
 #     (1.2 - 1.0) == 0.2 #=> false
 #
+# ## A Note About Precision
+#
+# For a calculation using a BigDecimal and another `value`, the precision of the
+# result depends on the type of `value`:
+#
+# *   If `value` is a Float, the precision is Float::DIG + 1.
+# *   If `value` is a Rational, the precision is larger than Float::DIG + 1.
+# *   If `value` is a BigDecimal, the precision is `value`'s precision in the
+#     internal representation, which is platform-dependent.
+# *   If `value` is other object, the precision is determined by the result of
+#     +BigDecimal(value)+.
+#
+#
 # ## Special features of accurate decimal arithmetic
 #
 # Because BigDecimal is more accurate than normal binary floating point
@@ -121,17 +135,36 @@
 # many other contributors.
 #
 class BigDecimal < Numeric
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - _load(p1)
+  # -->
   # Internal method used to provide marshalling support. See the Marshal module.
   #
   def self._load: (String) -> BigDecimal
 
-  # The BigDecimal.double_fig class method returns the number of digits a Float
-  # number is allowed to have. The result depends upon the CPU and OS in use.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.double_fig -> integer
+  # -->
+  # Returns the number of digits a Float object is allowed to have; the result is
+  # system-dependent:
+  #
+  #     BigDecimal.double_fig # => 16
   #
   def self.double_fig: () -> Integer
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - interpret_loosely(p1)
+  # -->
+  #
   def self.interpret_loosely: (string) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.limit(digits)
+  # -->
   # Limit the number of significant digits in newly created BigDecimal numbers to
   # the specified value. Rounding is performed as necessary, as specified by
   # BigDecimal.mode.
@@ -143,55 +176,172 @@ class BigDecimal < Numeric
   #
   def self.limit: (?Integer? digits) -> Integer
 
-  # Controls handling of arithmetic exceptions and rounding. If no value is
-  # supplied, the current value is returned.
-  #
-  # Six values of the mode parameter control the handling of arithmetic
-  # exceptions:
-  #
-  # BigDecimal::EXCEPTION_NaN BigDecimal::EXCEPTION_INFINITY
-  # BigDecimal::EXCEPTION_UNDERFLOW BigDecimal::EXCEPTION_OVERFLOW
-  # BigDecimal::EXCEPTION_ZERODIVIDE BigDecimal::EXCEPTION_ALL
-  #
-  # For each mode parameter above, if the value set is false, computation
-  # continues after an arithmetic exception of the appropriate type. When
-  # computation continues, results are as follows:
-  #
-  # EXCEPTION_NaN
-  # :   NaN
-  # EXCEPTION_INFINITY
-  # :   +Infinity or -Infinity
-  # EXCEPTION_UNDERFLOW
-  # :   0
-  # EXCEPTION_OVERFLOW
-  # :   +Infinity or -Infinity
-  # EXCEPTION_ZERODIVIDE
-  # :   +Infinity or -Infinity
-  #
-  #
-  # One value of the mode parameter controls the rounding of numeric values:
-  # BigDecimal::ROUND_MODE. The values it can take are:
-  #
-  # ROUND_UP, :up
-  # :   round away from zero
-  # ROUND_DOWN, :down, :truncate
-  # :   round towards zero (truncate)
-  # ROUND_HALF_UP, :half_up, :default
-  # :   round towards the nearest neighbor, unless both neighbors are equidistant,
-  #     in which case round away from zero. (default)
-  # ROUND_HALF_DOWN, :half_down
-  # :   round towards the nearest neighbor, unless both neighbors are equidistant,
-  #     in which case round towards zero.
-  # ROUND_HALF_EVEN, :half_even, :banker
-  # :   round towards the nearest neighbor, unless both neighbors are equidistant,
-  #     in which case round towards the even neighbor (Banker's rounding)
-  # ROUND_CEILING, :ceiling, :ceil
-  # :   round towards positive infinity (ceil)
-  # ROUND_FLOOR, :floor
-  # :   round towards negative infinity (floor)
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.mode(mode, setting = nil) -> integer
+  # -->
+  # Returns an integer representing the mode settings for exception handling and
+  # rounding.
+  #
+  # These modes control exception handling:
+  #
+  # *   BigDecimal::EXCEPTION_NaN.
+  # *   BigDecimal::EXCEPTION_INFINITY.
+  # *   BigDecimal::EXCEPTION_UNDERFLOW.
+  # *   BigDecimal::EXCEPTION_OVERFLOW.
+  # *   BigDecimal::EXCEPTION_ZERODIVIDE.
+  # *   BigDecimal::EXCEPTION_ALL.
+  #
+  #
+  # Values for `setting` for exception handling:
+  #
+  # *   `true`: sets the given `mode` to `true`.
+  # *   `false`: sets the given `mode` to `false`.
+  # *   `nil`: does not modify the mode settings.
+  #
+  #
+  # You can use method BigDecimal.save_exception_mode to temporarily change, and
+  # then automatically restore, exception modes.
+  #
+  # For clarity, some examples below begin by setting all exception modes to
+  # `false`.
+  #
+  # This mode controls the way rounding is to be performed:
+  #
+  # *   BigDecimal::ROUND_MODE
+  #
+  #
+  # You can use method BigDecimal.save_rounding_mode to temporarily change, and
+  # then automatically restore, the rounding mode.
+  #
+  # **NaNs**
+  #
+  # Mode BigDecimal::EXCEPTION_NaN controls behavior when a BigDecimal NaN is
+  # created.
+  #
+  # Settings:
+  #
+  # *   `false` (default): Returns `BigDecimal('NaN')`.
+  # *   `true`: Raises FloatDomainError.
+  #
+  #
+  # Examples:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0
+  #     BigDecimal('NaN')                                 # => NaN
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_NaN, true)  # => 2
+  #     BigDecimal('NaN') # Raises FloatDomainError
+  #
+  # **Infinities**
+  #
+  # Mode BigDecimal::EXCEPTION_INFINITY controls behavior when a BigDecimal
+  # Infinity or -Infinity is created. Settings:
+  #
+  # *   `false` (default): Returns `BigDecimal('Infinity')` or
+  #     `BigDecimal('-Infinity')`.
+  # *   `true`: Raises FloatDomainError.
+  #
+  #
+  # Examples:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)     # => 0
+  #     BigDecimal('Infinity')                                # => Infinity
+  #     BigDecimal('-Infinity')                               # => -Infinity
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_INFINITY, true) # => 1
+  #     BigDecimal('Infinity')  # Raises FloatDomainError
+  #     BigDecimal('-Infinity') # Raises FloatDomainError
+  #
+  # **Underflow**
+  #
+  # Mode BigDecimal::EXCEPTION_UNDERFLOW controls behavior when a BigDecimal
+  # underflow occurs. Settings:
+  #
+  # *   `false` (default): Returns `BigDecimal('0')` or `BigDecimal('-Infinity')`.
+  # *   `true`: Raises FloatDomainError.
+  #
+  #
+  # Examples:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)      # => 0
+  #     def flow_under
+  #       x = BigDecimal('0.1')
+  #       100.times { x *= x }
+  #     end
+  #     flow_under                                             # => 100
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_UNDERFLOW, true) # => 4
+  #     flow_under # Raises FloatDomainError
+  #
+  # **Overflow**
+  #
+  # Mode BigDecimal::EXCEPTION_OVERFLOW controls behavior when a BigDecimal
+  # overflow occurs. Settings:
+  #
+  # *   `false` (default): Returns `BigDecimal('Infinity')` or
+  #     `BigDecimal('-Infinity')`.
+  # *   `true`: Raises FloatDomainError.
+  #
+  #
+  # Examples:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)     # => 0
+  #     def flow_over
+  #       x = BigDecimal('10')
+  #       100.times { x *= x }
+  #     end
+  #     flow_over                                             # => 100
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_OVERFLOW, true) # => 1
+  #     flow_over # Raises FloatDomainError
+  #
+  # **Zero Division**
+  #
+  # Mode BigDecimal::EXCEPTION_ZERODIVIDE controls behavior when a zero-division
+  # occurs. Settings:
+  #
+  # *   `false` (default): Returns `BigDecimal('Infinity')` or
+  #     `BigDecimal('-Infinity')`.
+  # *   `true`: Raises FloatDomainError.
+  #
+  #
+  # Examples:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)       # => 0
+  #     one = BigDecimal('1')
+  #     zero = BigDecimal('0')
+  #     one / zero                                              # => Infinity
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ZERODIVIDE, true) # => 16
+  #     one / zero # Raises FloatDomainError
+  #
+  # **All Exceptions**
+  #
+  # Mode BigDecimal::EXCEPTION_ALL controls all of the above:
+  #
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0
+  #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, true)  # => 23
+  #
+  # **Rounding**
+  #
+  # Mode BigDecimal::ROUND_MODE controls the way rounding is to be performed; its
+  # `setting` values are:
+  #
+  # *   `ROUND_UP`: Round away from zero. Aliased as `:up`.
+  # *   `ROUND_DOWN`: Round toward zero. Aliased as `:down` and `:truncate`.
+  # *   `ROUND_HALF_UP`: Round toward the nearest neighbor; if the neighbors are
+  #     equidistant, round away from zero. Aliased as `:half_up` and `:default`.
+  # *   `ROUND_HALF_DOWN`: Round toward the nearest neighbor; if the neighbors are
+  #     equidistant, round toward zero. Aliased as `:half_down`.
+  # *   `ROUND_HALF_EVEN` (Banker's rounding): Round toward the nearest neighbor;
+  #     if the neighbors are equidistant, round toward the even neighbor. Aliased
+  #     as `:half_even` and `:banker`.
+  # *   `ROUND_CEILING`: Round toward positive infinity. Aliased as `:ceiling` and
+  #     `:ceil`.
+  # *   `ROUND_FLOOR`: Round toward negative infinity. Aliased as `:floor:`.
   #
   def self.mode: (Integer mode, ?Integer? value) -> Integer?
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.save_exception_mode { ... }
+  # -->
   # Execute the provided block, but preserve the exception mode
   #
   #     BigDecimal.save_exception_mode do
@@ -209,6 +359,10 @@ class BigDecimal < Numeric
   #
   def self.save_exception_mode: () { (?nil) -> void } -> void
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.save_limit { ... }
+  # -->
   # Execute the provided block, but preserve the precision limit
   #
   #     BigDecimal.limit(100)
@@ -221,6 +375,10 @@ class BigDecimal < Numeric
   #
   def self.save_limit: () { (?nil) -> void } -> void
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal.save_rounding_mode { ... }
+  # -->
   # Execute the provided block, but preserve the rounding mode
   #
   #     BigDecimal.save_rounding_mode do
@@ -236,93 +394,154 @@ class BigDecimal < Numeric
 
   public
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - a % b
+  #   - a.modulo(b)
+  # -->
   # Returns the modulus from dividing by b.
   #
   # See BigDecimal#divmod.
   #
   def %: (Numeric) -> BigDecimal
 
-  # Multiply by the specified value.
-  #
-  # e.g.
-  #     c = a.mult(b,n)
-  #     c = a * b
-  #
-  # digits
-  # :   If specified and less than the number of significant digits of the result,
-  #     the result is rounded to that number of digits, according to
-  #     BigDecimal.mode.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - *(p1)
+  # -->
   #
   def *: (Numeric) -> BigDecimal
 
-  # Returns the value raised to the power of n.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self ** other -> bigdecimal
+  # -->
+  # Returns the BigDecimal value of `self` raised to power `other`:
+  #
+  #     b = BigDecimal('3.14')
+  #     b ** 2              # => 0.98596e1
+  #     b ** 2.0            # => 0.98596e1
+  #     b ** Rational(2, 1) # => 0.98596e1
   #
-  # See BigDecimal#power.
+  # Related: BigDecimal#power.
   #
   def **: (Numeric) -> BigDecimal
 
-  # Add the specified value.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self + value -> bigdecimal
+  # -->
+  # Returns the BigDecimal sum of `self` and `value`:
   #
-  # e.g.
-  #     c = a.add(b,n)
-  #     c = a + b
+  #     b = BigDecimal('111111.111') # => 0.111111111e6
+  #     b + 2                        # => 0.111113111e6
+  #     b + 2.0                      # => 0.111113111e6
+  #     b + Rational(2, 1)           # => 0.111113111e6
+  #     b + Complex(2, 0)            # => (0.111113111e6+0i)
   #
-  # digits
-  # :   If specified and less than the number of significant digits of the result,
-  #     the result is rounded to that number of digits, according to
-  #     BigDecimal.mode.
+  # See the [Note About
+  # Precision](BigDecimal.html#class-BigDecimal-label-A+Note+About+Precision).
   #
   def +: (Numeric) -> BigDecimal
 
-  # Return self.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - +big_decimal -> self
+  # -->
+  # Returns `self`:
   #
-  #     +BigDecimal('5')  #=> 0.5e1
+  #     +BigDecimal(5)  # => 0.5e1
+  #     +BigDecimal(-5) # => -0.5e1
   #
   def +@: () -> BigDecimal
 
-  # Subtract the specified value.
-  #
-  # e.g.
-  #     c = a - b
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self - value -> bigdecimal
+  # -->
+  # Returns the BigDecimal difference of `self` and `value`:
   #
-  # The precision of the result value depends on the type of `b`.
+  #     b = BigDecimal('333333.333') # => 0.333333333e6
+  #     b - 2                        # => 0.333331333e6
+  #     b - 2.0                      # => 0.333331333e6
+  #     b - Rational(2, 1)           # => 0.333331333e6
+  #     b - Complex(2, 0)            # => (0.333331333e6+0i)
   #
-  # If `b` is a Float, the precision of the result is Float::DIG+1.
-  #
-  # If `b` is a BigDecimal, the precision of the result is `b`'s precision of
-  # internal representation from platform. So, it's return value is platform
-  # dependent.
+  # See the [Note About
+  # Precision](BigDecimal.html#class-BigDecimal-label-A+Note+About+Precision).
   #
   def -: (Numeric) -> BigDecimal
 
-  # Return the negation of self.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - -self -> bigdecimal
+  # -->
+  # Returns the BigDecimal negation of self:
   #
-  #     -BigDecimal('5')  #=> -0.5e1
+  #     b0 = BigDecimal('1.5')
+  #     b1 = -b0 # => -0.15e1
+  #     b2 = -b1 # => 0.15e1
   #
   def -@: () -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - a / b   -> bigdecimal
+  # -->
   # Divide by the specified value.
   #
-  # See BigDecimal#div.
+  # The result precision will be the precision of the larger operand, but its
+  # minimum is 2*Float::DIG.
+  #
+  # See BigDecimal#div. See BigDecimal#quo.
   #
   def /: (Numeric) -> BigDecimal
 
-  # Returns true if a is less than b.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self < other -> true or false
+  # -->
+  # Returns `true` if `self` is less than `other`, `false` otherwise:
   #
-  # Values may be coerced to perform the comparison (see ==, BigDecimal#coerce).
+  #     b = BigDecimal('1.5') # => 0.15e1
+  #     b < 2                 # => true
+  #     b < 2.0               # => true
+  #     b < Rational(2, 1)    # => true
+  #     b < 1.5               # => false
+  #
+  # Raises an exception if the comparison cannot be made.
   #
   def <: (Numeric) -> bool
 
-  # Returns true if a is less than or equal to b.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self <= other -> true or false
+  # -->
+  # Returns `true` if `self` is less or equal to than `other`, `false` otherwise:
+  #
+  #     b = BigDecimal('1.5') # => 0.15e1
+  #     b <= 2                # => true
+  #     b <= 2.0              # => true
+  #     b <= Rational(2, 1)   # => true
+  #     b <= 1.5              # => true
+  #     b < 1                 # => false
   #
-  # Values may be coerced to perform the comparison (see ==, BigDecimal#coerce).
+  # Raises an exception if the comparison cannot be made.
   #
   def <=: (Numeric) -> bool
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - <=>(p1)
+  # -->
   # The comparison operator. a <=> b is 0 if a == b, 1 if a > b, -1 if a < b.
   #
   def <=>: (untyped) -> Integer?
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - ==(p1)
+  # -->
   # Tests for value equality; returns true if the values are equal.
   #
   # The == and === operators and the eql? method have the same implementation for
@@ -334,6 +553,7 @@ class BigDecimal < Numeric
   #
   def ==: (untyped) -> bool
 
+  # <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
   # Tests for value equality; returns true if the values are equal.
   #
   # The == and === operators and the eql? method have the same implementation for
@@ -345,49 +565,92 @@ class BigDecimal < Numeric
   #
   def ===: (untyped) -> bool
 
-  # Returns true if a is greater than b.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self > other -> true or false
+  # -->
+  # Returns `true` if `self` is greater than `other`, `false` otherwise:
   #
-  # Values may be coerced to perform the comparison (see ==, BigDecimal#coerce).
+  #     b = BigDecimal('1.5')
+  #     b > 1              # => true
+  #     b > 1.0            # => true
+  #     b > Rational(1, 1) # => true
+  #     b > 2              # => false
+  #
+  # Raises an exception if the comparison cannot be made.
   #
   def >: (Numeric) -> bool
 
-  # Returns true if a is greater than or equal to b.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - self >= other -> true or false
+  # -->
+  # Returns `true` if `self` is greater than or equal to `other`, `false`
+  # otherwise:
+  #
+  #     b = BigDecimal('1.5')
+  #     b >= 1              # => true
+  #     b >= 1.0            # => true
+  #     b >= Rational(1, 1) # => true
+  #     b >= 1.5            # => true
+  #     b > 2               # => false
   #
-  # Values may be coerced to perform the comparison (see ==, BigDecimal#coerce)
+  # Raises an exception if the comparison cannot be made.
   #
   def >=: (Numeric) -> bool
 
-  # Method used to provide marshalling support.
-  #
-  #     inf = BigDecimal('Infinity')
-  #       #=> Infinity
-  #     BigDecimal._load(inf._dump)
-  #       #=> Infinity
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - _dump -> string
+  # -->
+  # Returns a string representing the marshalling of `self`. See module Marshal.
   #
-  # See the Marshal module.
+  #     inf = BigDecimal('Infinity') # => Infinity
+  #     dumped = inf._dump           # => "9:Infinity"
+  #     BigDecimal._load(dumped)     # => Infinity
   #
   def _dump: (?untyped) -> String
 
-  # Returns the absolute value, as a BigDecimal.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - abs -> bigdecimal
+  # -->
+  # Returns the BigDecimal absolute value of `self`:
   #
-  #     BigDecimal('5').abs  #=> 0.5e1
-  #     BigDecimal('-3').abs #=> 0.3e1
+  #     BigDecimal('5').abs  # => 0.5e1
+  #     BigDecimal('-3').abs # => 0.3e1
   #
   def abs: () -> BigDecimal
 
-  # Add the specified value.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - add(value, ndigits) -> new_bigdecimal
+  # -->
+  # Returns the BigDecimal sum of `self` and `value` with a precision of `ndigits`
+  # decimal digits.
   #
-  # e.g.
-  #     c = a.add(b,n)
-  #     c = a + b
+  # When `ndigits` is less than the number of significant digits in the sum, the
+  # sum is rounded to that number of digits, according to the current rounding
+  # mode; see BigDecimal.mode.
   #
-  # digits
-  # :   If specified and less than the number of significant digits of the result,
-  #     the result is rounded to that number of digits, according to
-  #     BigDecimal.mode.
+  # Examples:
+  #
+  #     # Set the rounding mode.
+  #     BigDecimal.mode(BigDecimal::ROUND_MODE, :half_up)
+  #     b = BigDecimal('111111.111')
+  #     b.add(1, 0)               # => 0.111112111e6
+  #     b.add(1, 3)               # => 0.111e6
+  #     b.add(1, 6)               # => 0.111112e6
+  #     b.add(1, 15)              # => 0.111112111e6
+  #     b.add(1.0, 15)            # => 0.111112111e6
+  #     b.add(Rational(1, 1), 15) # => 0.111112111e6
   #
   def add: (Numeric value, Integer digits) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - ceil(n)
+  # -->
   # Return the smallest integer greater than or equal to the value, as a
   # BigDecimal.
   #
@@ -406,8 +669,17 @@ class BigDecimal < Numeric
   def ceil: () -> Integer
           | (int n) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - clone()
+  # -->
+  #
   def clone: () -> self
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - coerce(p1)
+  # -->
   # The coerce method provides support for Ruby type coercion. It is not enabled
   # by default.
   #
@@ -422,8 +694,13 @@ class BigDecimal < Numeric
   # Note that coercing a String to a BigDecimal is not supported by default; it
   # requires a special compile-time option when building Ruby.
   #
-  def coerce: (Numeric) -> [BigDecimal, BigDecimal]
+  def coerce: (Numeric) -> [ BigDecimal, BigDecimal ]
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - div(value)  -> integer
+  #   - div(value, digits)  -> bigdecimal or integer
+  # -->
   # Divide by the specified value.
   #
   # digits
@@ -437,6 +714,8 @@ class BigDecimal < Numeric
   #     Float#div; see also BigDecimal#divmod.
   #
   #
+  # See BigDecimal#/. See BigDecimal#quo.
+  #
   # Examples:
   #
   #     a = BigDecimal("4")
@@ -453,6 +732,10 @@ class BigDecimal < Numeric
   def div: (Numeric value) -> Integer
          | (Numeric value, int digits) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - divmod(value)
+  # -->
   # Divides by the specified value, and returns the quotient and modulus as
   # BigDecimal numbers. The quotient is rounded towards negative infinity.
   #
@@ -472,10 +755,16 @@ class BigDecimal < Numeric
   # The quotient q is (a/b).floor, and the modulus is the amount that must be
   # added to q * b to get a.
   #
-  def divmod: (Numeric) -> [BigDecimal, BigDecimal]
+  def divmod: (Numeric) -> [ BigDecimal, BigDecimal ]
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - dup()
+  # -->
+  #
   def dup: () -> self
 
+  # <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
   # Tests for value equality; returns true if the values are equal.
   #
   # The == and === operators and the eql? method have the same implementation for
@@ -487,6 +776,10 @@ class BigDecimal < Numeric
   #
   def eql?: (untyped) -> bool
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - exponent()
+  # -->
   # Returns the exponent of the BigDecimal number, as an Integer.
   #
   # If the number can be represented as 0.xxxxxx*10**n where xxxxxx is a string of
@@ -494,14 +787,26 @@ class BigDecimal < Numeric
   #
   def exponent: () -> Integer
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - finite?()
+  # -->
   # Returns True if the value is finite (not NaN or infinite).
   #
   def finite?: () -> bool
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - fix()
+  # -->
   # Return the integer part of the number, as a BigDecimal.
   #
   def fix: () -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - floor(n)
+  # -->
   # Return the largest integer less than or equal to the value, as a BigDecimal.
   #
   #     BigDecimal('3.14159').floor #=> 3
@@ -519,22 +824,42 @@ class BigDecimal < Numeric
   def floor: () -> Integer
            | (int n) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - frac()
+  # -->
   # Return the fractional part of the number, as a BigDecimal.
   #
   def frac: () -> BigDecimal
 
-  # Creates a hash for this BigDecimal.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - hash -> integer
+  # -->
+  # Returns the integer hash value for `self`.
+  #
+  # Two instances of BigDecimal have the same hash value if and only if they have
+  # equal:
   #
-  # Two BigDecimals with equal sign, fractional part and exponent have the same
-  # hash.
+  # *   Sign.
+  # *   Fractional part.
+  # *   Exponent.
   #
   def hash: () -> Integer
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - infinite?()
+  # -->
   # Returns nil, -1, or +1 depending on whether the value is finite, -Infinity, or
   # +Infinity.
   #
   def infinite?: () -> Integer?
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - inspect()
+  # -->
   # Returns a string representation of self.
   #
   #     BigDecimal("1234.5678").inspect
@@ -542,33 +867,60 @@ class BigDecimal < Numeric
   #
   def inspect: () -> String
 
+  # <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
   # Returns the modulus from dividing by b.
   #
   # See BigDecimal#divmod.
   #
   def modulo: (Numeric b) -> BigDecimal
 
-  # Multiply by the specified value.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - mult(other, ndigits) -> bigdecimal
+  # -->
+  # Returns the BigDecimal product of `self` and `value` with a precision of
+  # `ndigits` decimal digits.
   #
-  # e.g.
-  #     c = a.mult(b,n)
-  #     c = a * b
+  # When `ndigits` is less than the number of significant digits in the sum, the
+  # sum is rounded to that number of digits, according to the current rounding
+  # mode; see BigDecimal.mode.
   #
-  # digits
-  # :   If specified and less than the number of significant digits of the result,
-  #     the result is rounded to that number of digits, according to
-  #     BigDecimal.mode.
+  # Examples:
+  #
+  #     # Set the rounding mode.
+  #     BigDecimal.mode(BigDecimal::ROUND_MODE, :half_up)
+  #     b = BigDecimal('555555.555')
+  #     b.mult(3, 0)              # => 0.1666666665e7
+  #     b.mult(3, 3)              # => 0.167e7
+  #     b.mult(3, 6)              # => 0.166667e7
+  #     b.mult(3, 15)             # => 0.1666666665e7
+  #     b.mult(3.0, 0)            # => 0.1666666665e7
+  #     b.mult(Rational(3, 1), 0) # => 0.1666666665e7
+  #     b.mult(Complex(3, 0), 0)  # => (0.1666666665e7+0.0i)
   #
   def mult: (Numeric value, int digits) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - nan?()
+  # -->
   # Returns True if the value is Not a Number.
   #
   def nan?: () -> bool
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - nonzero?()
+  # -->
   # Returns self if the value is non-zero, nil otherwise.
   #
   def nonzero?: () -> self?
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - power(n)
+  #   - power(n, prec)
+  # -->
   # Returns the value raised to the power of n.
   #
   # Note that n must be an Integer.
@@ -577,28 +929,53 @@ class BigDecimal < Numeric
   #
   def power: (Numeric n, int prec) -> BigDecimal
 
-  # Returns an Array of two Integer values.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - precs -> array
+  # -->
+  # Returns an Array of two Integer values that represent platform-dependent
+  # internal storage properties.
+  #
+  # This method is deprecated and will be removed in the future. Instead, use
+  # BigDecimal#n_significant_digits for obtaining the number of significant digits
+  # in scientific notation, and BigDecimal#precision for obtaining the number of
+  # digits in decimal notation.
+  #
+  def precs: () -> [ Integer, Integer ]
+
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - quo(value)  -> bigdecimal
+  #   - quo(value, digits)  -> bigdecimal
+  # -->
+  # Divide by the specified value.
   #
-  # The first value is the current number of significant digits in the BigDecimal.
-  # The second value is the maximum number of significant digits for the
-  # BigDecimal.
+  # digits
+  # :   If specified and less than the number of significant digits of the result,
+  #     the result is rounded to the given number of digits, according to the
+  #     rounding mode indicated by BigDecimal.mode.
   #
-  #     BigDecimal('5').precs #=> [9, 18]
+  #     If digits is 0 or omitted, the result is the same as for the / operator.
   #
-  def precs: () -> [Integer, Integer]
-
-  # Divide by the specified value.
   #
-  # See BigDecimal#div.
+  # See BigDecimal#/. See BigDecimal#div.
   #
   def quo: (Numeric) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - remainder(value)
+  # -->
   # Returns the remainder from dividing by the value.
   #
   # x.remainder(y) means x-y*(x/y).truncate
   #
   def remainder: (Numeric) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - round(n, mode)
+  # -->
   # Round to the nearest integer (by default), returning the result as a
   # BigDecimal if n is specified, or as an Integer if it isn't.
   #
@@ -613,10 +990,10 @@ class BigDecimal < Numeric
   # than that many digits.
   #
   # If n is specified and negative, at least that many digits to the left of the
-  # decimal point will be 0 in the result.
+  # decimal point will be 0 in the result, and return value will be an Integer.
   #
   #     BigDecimal('3.14159').round(3) #=> 3.142
-  #     BigDecimal('13345.234').round(-2) #=> 13300.0
+  #     BigDecimal('13345.234').round(-2) #=> 13300
   #
   # The value of the optional mode argument can be used to determine how rounding
   # is performed; see BigDecimal.mode.
@@ -624,6 +1001,10 @@ class BigDecimal < Numeric
   def round: () -> Integer
            | (Numeric n, ?Integer mode) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - sign()
+  # -->
   # Returns the sign of the value.
   #
   # Returns a positive value if > 0, a negative value if < 0, and a zero if == 0.
@@ -648,6 +1029,10 @@ class BigDecimal < Numeric
   #
   def sign: () -> Integer
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - split()
+  # -->
   # Splits a BigDecimal number into four parts, returned as an array of values.
   #
   # The first value represents the sign of the BigDecimal, and is -1 or 1, or 0 if
@@ -672,14 +1057,22 @@ class BigDecimal < Numeric
   # (Note that the to_f method is provided as a more convenient way to translate a
   # BigDecimal to a Float.)
   #
-  def split: () -> [Integer, String, Integer, Integer]
+  def split: () -> [ Integer, String, Integer, Integer ]
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - sqrt(n)
+  # -->
   # Returns the square root of the value.
   #
   # Result has at least n significant digits.
   #
   def sqrt: (int n) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - sub(value, digits)  -> bigdecimal
+  # -->
   # Subtract the specified value.
   #
   # e.g.
@@ -692,28 +1085,45 @@ class BigDecimal < Numeric
   #
   def sub: (Numeric value, int digits) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - to_f()
+  # -->
   # Returns a new Float object having approximately the same value as the
   # BigDecimal number. Normal accuracy limits and built-in errors of binary Float
   # arithmetic apply.
   #
   def to_f: () -> Float
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - to_i()
+  # -->
   # Returns the value as an Integer.
   #
   # If the BigDecimal is infinity or NaN, raises FloatDomainError.
   #
   def to_i: () -> Integer
 
+  # <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
   # Returns the value as an Integer.
   #
   # If the BigDecimal is infinity or NaN, raises FloatDomainError.
   #
   def to_int: () -> Integer
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - to_r()
+  # -->
   # Converts a BigDecimal to a Rational.
   #
   def to_r: () -> Rational
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - to_s(s)
+  # -->
   # Converts the value to a string.
   #
   # The default format looks like  0.xxxxEnn.
@@ -744,8 +1154,12 @@ class BigDecimal < Numeric
   #     BigDecimal('123.45678901234567890').to_s(' F')
   #       #=> ' 123.4567890123456789'
   #
-  def to_s: (?(String | int) s) -> String
+  def to_s: (?String | int s) -> String
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - truncate(n)
+  # -->
   # Truncate to the nearest integer (by default), returning the result as a
   # BigDecimal.
   #
@@ -765,6 +1179,10 @@ class BigDecimal < Numeric
   def truncate: () -> Integer
               | (int n) -> BigDecimal
 
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - zero?()
+  # -->
   # Returns True if the value is zero.
   #
   def zero?: () -> bool
@@ -774,6 +1192,7 @@ class BigDecimal < Numeric
   def initialize_copy: (self) -> self
 end
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Base value used in internal calculations.  On a 32 bit system, BASE is 10000,
 # indicating that calculation is done in groups of 4 digits. (If it were larger,
 # BASE**2 wouldn't fit in 32 bits, so you couldn't guarantee that two groups
@@ -781,151 +1200,181 @@ end
 #
 BigDecimal::BASE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines whether overflow, underflow or zero divide result in an exception
 # being thrown. See BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_ALL: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when the result of a computation is infinity.  See
 # BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_INFINITY: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when the result of a computation is not a number
 # (NaN). See BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_NaN: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when the result of a computation is an overflow (a
 # result too large to be represented). See BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_OVERFLOW: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when the result of a computation is an underflow (a
 # result too small to be represented). See BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_UNDERFLOW: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when a division by zero is performed. See
 # BigDecimal.mode.
 #
 BigDecimal::EXCEPTION_ZERODIVIDE: Integer
 
-# Positive infinity value.
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
+# Special value constants
 #
 BigDecimal::INFINITY: BigDecimal
 
-# 'Not a Number' value.
-#
 BigDecimal::NAN: BigDecimal
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Round towards +Infinity. See BigDecimal.mode.
 #
 BigDecimal::ROUND_CEILING: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that values should be rounded towards zero. See BigDecimal.mode.
 #
 BigDecimal::ROUND_DOWN: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Round towards -Infinity. See BigDecimal.mode.
 #
 BigDecimal::ROUND_FLOOR: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that digits >= 6 should be rounded up, others rounded down. See
 # BigDecimal.mode.
 #
 BigDecimal::ROUND_HALF_DOWN: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Round towards the even neighbor. See BigDecimal.mode.
 #
 BigDecimal::ROUND_HALF_EVEN: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that digits >= 5 should be rounded up, others rounded down. See
 # BigDecimal.mode.
 #
 BigDecimal::ROUND_HALF_UP: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Determines what happens when a result must be rounded in order to fit in the
 # appropriate number of significant digits. See BigDecimal.mode.
 #
 BigDecimal::ROUND_MODE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that values should be rounded away from zero. See BigDecimal.mode.
 #
 BigDecimal::ROUND_UP: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is negative and finite. See BigDecimal.sign.
 #
 BigDecimal::SIGN_NEGATIVE_FINITE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is negative and infinite. See BigDecimal.sign.
 #
 BigDecimal::SIGN_NEGATIVE_INFINITE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is -0. See BigDecimal.sign.
 #
 BigDecimal::SIGN_NEGATIVE_ZERO: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is not a number. See BigDecimal.sign.
 #
 BigDecimal::SIGN_NaN: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is positive and finite. See BigDecimal.sign.
 #
 BigDecimal::SIGN_POSITIVE_FINITE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is positive and infinite. See BigDecimal.sign.
 #
 BigDecimal::SIGN_POSITIVE_INFINITE: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # Indicates that a value is +0. See BigDecimal.sign.
 #
 BigDecimal::SIGN_POSITIVE_ZERO: Integer
 
+# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
 # The version of bigdecimal library
 #
 BigDecimal::VERSION: String
 
+%a{annotate:rdoc:skip}
 module Kernel
   private
 
-  # Create a new BigDecimal object.
+  # <!--
+  #   rdoc-file=ext/bigdecimal/bigdecimal.c
+  #   - BigDecimal(value, exception: true) -> bigdecimal
+  #   - BigDecimal(value, ndigits, exception: true) -> bigdecimal
+  # -->
+  # Returns the \BigDecimal converted from +value+
+  #     with a precision of +ndigits+ decimal digits.
   #
-  # initial
-  # :   The initial value, as an Integer, a Float, a Rational, a BigDecimal, or a
-  #     String.
+  #     When +ndigits+ is less than the number of significant digits
+  #     in the value, the result is rounded to that number of digits,
+  #     according to the current rounding mode; see BigDecimal.mode.
   #
-  #     If it is a String, spaces are ignored and unrecognized characters
-  #     terminate the value.
+  # Returns `value` converted to a BigDecimal, depending on the type of `value`:
   #
-  # digits
-  # :   The number of significant digits, as an Integer. If omitted or 0, the
-  #     number of significant digits is determined from the initial value.
+  # *   Integer, Float, Rational, Complex, or BigDecimal: converted directly:
+  #
+  #         # Integer, Complex, or BigDecimal value does not require ndigits; ignored if given.
+  #         BigDecimal(2)                     # => 0.2e1
+  #         BigDecimal(Complex(2, 0))         # => 0.2e1
+  #         BigDecimal(BigDecimal(2))         # => 0.2e1
+  #         # Float or Rational value requires ndigits.
+  #         BigDecimal(2.0, 0)                # => 0.2e1
+  #         BigDecimal(Rational(2, 1), 0)     # => 0.2e1
   #
-  #     The actual number of significant digits used in computation is usually
-  #     larger than the specified number.
+  # *   String: converted by parsing if it contains an integer or floating-point
+  #     literal; leading and trailing whitespace is ignored:
   #
-  # exception
-  # :   Whether an exception should be raised on invalid arguments. `true` by
-  #     default, if passed `false`, just returns `nil` for invalid.
+  #         # String does not require ndigits; ignored if given.
+  #         BigDecimal('2')     # => 0.2e1
+  #         BigDecimal('2.0')   # => 0.2e1
+  #         BigDecimal('0.2e1') # => 0.2e1
+  #         BigDecimal(' 2.0 ') # => 0.2e1
   #
+  # *   Other type that responds to method `:to_str`: first converted to a string,
+  #     then converted to a BigDecimal, as above.
   #
-  # #### Exceptions
+  # *   Other type:
   #
-  # TypeError
-  # :   If the `initial` type is neither Integer, Float, Rational, nor BigDecimal,
-  #     this exception is raised.
+  #     *   Raises an exception if keyword argument `exception` is `true`.
+  #     *   Returns `nil` if keyword argument `exception` is `true`.
   #
-  # TypeError
-  # :   If the `digits` is not an Integer, this exception is raised.
   #
-  # ArgumentError
-  # :   If `initial` is a Float, and the `digits` is larger than Float::DIG + 1,
-  #     this exception is raised.
   #
-  # ArgumentError
-  # :   If the `initial` is a Float or Rational, and the `digits` value is
-  #     omitted, this exception is raised.
+  # Raises an exception if `value` evaluates to a Float and `digits` is larger
+  # than Float::DIG + 1.
   #
-  def self?.BigDecimal: ((real | string | BigDecimal) initial, ?int digits, ?exception: bool) -> BigDecimal
+  def self?.BigDecimal: (real | string | BigDecimal initial, ?int digits, ?exception: bool) -> BigDecimal
 end