steep 0.14.0 → 0.15.0

data/vendor/ruby-signature/stdlib/builtin/marshal.rbs

@@ -1,135 +1,161 @@
 # The marshaling library converts collections of Ruby objects into a byte
-# stream, allowing them to be stored outside the currently active script.
-# This data may subsequently be read and the original objects
-# reconstituted.
-# 
+# stream, allowing them to be stored outside the currently active script. This
+# data may subsequently be read and the original objects reconstituted.
+#
 # Marshaled data has major and minor version numbers stored along with the
-# object information. In normal use, marshaling can only load data written
-# with the same major version number and an equal or lower minor version
-# number. If Ruby’s “verbose” flag is set (normally using -d, -v, -w, or
-# –verbose) the major and minor numbers must match exactly.
-# [Marshal](Marshal) versioning is independent of
-# Ruby’s version numbers. You can extract the version by reading the
-# first two bytes of marshaled data.
-# 
-# ```ruby
-# str = Marshal.dump("thing")
-# RUBY_VERSION   #=> "1.9.0"
-# str[0].ord     #=> 4
-# str[1].ord     #=> 8
-# ```
-# 
-# Some objects cannot be dumped: if the objects to be dumped include
-# bindings, procedure or method objects, instances of class
-# [IO](https://ruby-doc.org/core-2.6.3/IO.html), or singleton objects, a
-# [TypeError](https://ruby-doc.org/core-2.6.3/TypeError.html) will be
-# raised.
-# 
-# If your class has special serialization needs (for example, if you want
-# to serialize in some specific format), or if it contains objects that
-# would otherwise not be serializable, you can implement your own
-# serialization strategy.
-# 
+# object information. In normal use, marshaling can only load data written with
+# the same major version number and an equal or lower minor version number. If
+# Ruby's ``verbose'' flag is set (normally using -d, -v, -w, or --verbose) the
+# major and minor numbers must match exactly. Marshal versioning is independent
+# of Ruby's version numbers. You can extract the version by reading the first
+# two bytes of marshaled data.
+#
+#     str = Marshal.dump("thing")
+#     RUBY_VERSION   #=> "1.9.0"
+#     str[0].ord     #=> 4
+#     str[1].ord     #=> 8
+#
+# Some objects cannot be dumped: if the objects to be dumped include bindings,
+# procedure or method objects, instances of class IO, or singleton objects, a
+# TypeError will be raised.
+#
+# If your class has special serialization needs (for example, if you want to
+# serialize in some specific format), or if it contains objects that would
+# otherwise not be serializable, you can implement your own serialization
+# strategy.
+#
 # There are two methods of doing this, your object can define either
-# marshal\_dump and marshal\_load or \_dump and \_load. marshal\_dump will
-# take precedence over \_dump if both are defined. marshal\_dump may
-# result in smaller [Marshal](Marshal) strings.
-# 
-# 
-# By design, [::load](Marshal#method-c-load) can
-# deserialize almost any class loaded into the Ruby process. In many cases
-# this can lead to remote code execution if the
-# [Marshal](Marshal) data is loaded from an untrusted
-# source.
-# 
-# As a result, [::load](Marshal#method-c-load) is not
-# suitable as a general purpose serialization format and you should never
-# unmarshal user supplied input or other untrusted data.
-# 
-# If you need to deserialize untrusted data, use JSON or another
-# serialization format that is only able to load simple, ‘primitive’ types
-# such as [String](https://ruby-doc.org/core-2.6.3/String.html),
-# [Array](https://ruby-doc.org/core-2.6.3/Array.html),
-# [Hash](https://ruby-doc.org/core-2.6.3/Hash.html), etc. Never allow
-# user input to specify arbitrary types to deserialize into.
-# 
-# 
-# When dumping an object the method marshal\_dump will be called.
-# marshal\_dump must return a result containing the information necessary
-# for marshal\_load to reconstitute the object. The result can be any
-# object.
-# 
-# When loading an object dumped using marshal\_dump the object is first
-# allocated then marshal\_load is called with the result from
-# marshal\_dump. marshal\_load must recreate the object from the
-# information in the result.
-# 
+# marshal_dump and marshal_load or _dump and _load.  marshal_dump will take
+# precedence over _dump if both are defined.  marshal_dump may result in smaller
+# Marshal strings.
+#
+# ## Security considerations
+#
+# By design, Marshal.load can deserialize almost any class loaded into the Ruby
+# process. In many cases this can lead to remote code execution if the Marshal
+# data is loaded from an untrusted source.
+#
+# As a result, Marshal.load is not suitable as a general purpose serialization
+# format and you should never unmarshal user supplied input or other untrusted
+# data.
+#
+# If you need to deserialize untrusted data, use JSON or another serialization
+# format that is only able to load simple, 'primitive' types such as String,
+# Array, Hash, etc. Never allow user input to specify arbitrary types to
+# deserialize into.
+#
+# ## marshal_dump and marshal_load
+#
+# When dumping an object the method marshal_dump will be called. marshal_dump
+# must return a result containing the information necessary for marshal_load to
+# reconstitute the object.  The result can be any object.
+#
+# When loading an object dumped using marshal_dump the object is first allocated
+# then marshal_load is called with the result from marshal_dump. marshal_load
+# must recreate the object from the information in the result.
+#
 # Example:
-# 
-# ```ruby
-# class MyObj
-#   def initialize name, version, data
-#     @name    = name
-#     @version = version
-#     @data    = data
-#   end
-# 
-#   def marshal_dump
-#     [@name, @version]
-#   end
-# 
-#   def marshal_load array
-#     @name, @version = array
-#   end
-# end
-# ```
-# 
-# 
-# Use \_dump and \_load when you need to allocate the object you’re
-# restoring yourself.
-# 
-# When dumping an object the instance method \_dump is called with an
-# [Integer](https://ruby-doc.org/core-2.6.3/Integer.html) which indicates
-# the maximum depth of objects to dump (a value of -1 implies that you
-# should disable depth checking). \_dump must return a
-# [String](https://ruby-doc.org/core-2.6.3/String.html) containing the
-# information necessary to reconstitute the object.
-# 
-# The class method \_load should take a
-# [String](https://ruby-doc.org/core-2.6.3/String.html) and use it to
-# return an object of the same class.
-# 
+#
+#     class MyObj
+#       def initialize name, version, data
+#         @name    = name
+#         @version = version
+#         @data    = data
+#       end
+#
+#       def marshal_dump
+#         [@name, @version]
+#       end
+#
+#       def marshal_load array
+#         @name, @version = array
+#       end
+#     end
+#
+# ## _dump and _load
+#
+# Use _dump and _load when you need to allocate the object you're restoring
+# yourself.
+#
+# When dumping an object the instance method _dump is called with an Integer
+# which indicates the maximum depth of objects to dump (a value of -1 implies
+# that you should disable depth checking).  _dump must return a String
+# containing the information necessary to reconstitute the object.
+#
+# The class method _load should take a String and use it to return an object of
+# the same class.
+#
 # Example:
-# 
-# ```ruby
-# class MyObj
-#   def initialize name, version, data
-#     @name    = name
-#     @version = version
-#     @data    = data
-#   end
-# 
-#   def _dump level
-#     [@name, @version].join ':'
-#   end
-# 
-#   def self._load args
-#     new(*args.split(':'))
-#   end
-# end
-# ```
-# 
-# Since [::dump](Marshal#method-c-dump) outputs a
-# string you can have \_dump return a
-# [Marshal](Marshal) string which is Marshal.loaded in
-# \_load for complex objects.
+#
+#     class MyObj
+#       def initialize name, version, data
+#         @name    = name
+#         @version = version
+#         @data    = data
+#       end
+#
+#       def _dump level
+#         [@name, @version].join ':'
+#       end
+#
+#       def self._load args
+#         new(*args.split(':'))
+#       end
+#     end
+#
+# Since Marshal.dump outputs a string you can have _dump return a Marshal string
+# which is Marshal.loaded in _load for complex objects.
+#
 module Marshal
+  # Serializes obj and all descendant objects. If anIO is specified, the
+  # serialized data will be written to it, otherwise the data will be returned as
+  # a String. If limit is specified, the traversal of subobjects will be limited
+  # to that depth. If limit is negative, no checking of depth will be performed.
+  #
+  #     class Klass
+  #       def initialize(str)
+  #         @str = str
+  #       end
+  #       def say_hello
+  #         @str
+  #       end
+  #     end
+  #
+  # (produces no output)
+  #
+  #     o = Klass.new("hello\n")
+  #     data = Marshal.dump(o)
+  #     obj = Marshal.load(data)
+  #     obj.say_hello  #=> "hello\n"
+  #
+  # Marshal can't dump following objects:
+  # *   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,
+  #     ThreadGroup, Continuation
+  # *   objects which define singleton methods
+  #
   def self.dump: (Object arg0, ?IO arg1, ?Integer arg2) -> Object
                | (Object arg0, ?Integer arg1) -> Object
 
+  # Returns the result of converting the serialized data in source into a Ruby
+  # object (possibly with associated subordinate objects). source may be either an
+  # instance of IO or an object that responds to to_str. If proc is specified,
+  # each object will be passed to the proc, as the object is being deserialized.
+  #
+  # Never pass untrusted data (including user supplied input) to this method.
+  # Please see the overview for further details.
+  #
   def self.load: (String arg0, ?Proc arg1) -> Object
+
+  alias self.restore self.load
 end
 
+# major version
+#
 Marshal::MAJOR_VERSION: Integer
 
+# minor version
+#
 Marshal::MINOR_VERSION: Integer

data/vendor/ruby-signature/stdlib/builtin/math.rbs

@@ -1,66 +1,369 @@
-# The [Math](Math) module contains module functions
-# for basic trigonometric and transcendental functions. See class
-# [Float](https://ruby-doc.org/core-2.6.3/Float.html) for a list of
-# constants that define Ruby's floating point accuracy.
-# 
+# The Math module contains module functions for basic trigonometric and
+# transcendental functions. See class Float for a list of constants that define
+# Ruby's floating point accuracy.
+#
 # Domains and codomains are given only for real (not complex) numbers.
+#
 module Math
+  # Computes the arc cosine of `x`. Returns 0..PI.
+  #
+  # Domain: [-1, 1]
+  #
+  # Codomain: [0, PI]
+  #
+  #     Math.acos(0) == Math::PI/2  #=> true
+  #
   def self.acos: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the inverse hyperbolic cosine of `x`.
+  #
+  # Domain: [1, INFINITY)
+  #
+  # Codomain: [0, INFINITY)
+  #
+  #     Math.acosh(1) #=> 0.0
+  #
   def self.acosh: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the arc sine of `x`. Returns -PI/2..PI/2.
+  #
+  # Domain: [-1, -1]
+  #
+  # Codomain: [-PI/2, PI/2]
+  #
+  #     Math.asin(1) == Math::PI/2  #=> true
+  #
   def self.asin: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the inverse hyperbolic sine of `x`.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.asinh(1) #=> 0.881373587019543
+  #
   def self.asinh: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the arc tangent of `x`. Returns -PI/2..PI/2.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-PI/2, PI/2)
+  #
+  #     Math.atan(0) #=> 0.0
+  #
   def self.atan: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the arc tangent given `y` and `x`. Returns a Float in the range
+  # -PI..PI. Return value is a angle in radians between the positive x-axis of
+  # cartesian plane and the point given by the coordinates (`x`, `y`) on it.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: [-PI, PI]
+  #
+  #     Math.atan2(-0.0, -1.0) #=> -3.141592653589793
+  #     Math.atan2(-1.0, -1.0) #=> -2.356194490192345
+  #     Math.atan2(-1.0, 0.0)  #=> -1.5707963267948966
+  #     Math.atan2(-1.0, 1.0)  #=> -0.7853981633974483
+  #     Math.atan2(-0.0, 1.0)  #=> -0.0
+  #     Math.atan2(0.0, 1.0)   #=> 0.0
+  #     Math.atan2(1.0, 1.0)   #=> 0.7853981633974483
+  #     Math.atan2(1.0, 0.0)   #=> 1.5707963267948966
+  #     Math.atan2(1.0, -1.0)  #=> 2.356194490192345
+  #     Math.atan2(0.0, -1.0)  #=> 3.141592653589793
+  #     Math.atan2(INFINITY, INFINITY)   #=> 0.7853981633974483
+  #     Math.atan2(INFINITY, -INFINITY)  #=> 2.356194490192345
+  #     Math.atan2(-INFINITY, INFINITY)  #=> -0.7853981633974483
+  #     Math.atan2(-INFINITY, -INFINITY) #=> -2.356194490192345
+  #
   def self.atan2: (Integer | Float | Rational | BigDecimal y, Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the inverse hyperbolic tangent of `x`.
+  #
+  # Domain: (-1, 1)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.atanh(1) #=> Infinity
+  #
   def self.atanh: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Returns the cube root of `x`.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     -9.upto(9) {|x|
+  #       p [x, Math.cbrt(x), Math.cbrt(x)**3]
+  #     }
+  #     #=> [-9, -2.0800838230519, -9.0]
+  #     #   [-8, -2.0, -8.0]
+  #     #   [-7, -1.91293118277239, -7.0]
+  #     #   [-6, -1.81712059283214, -6.0]
+  #     #   [-5, -1.7099759466767, -5.0]
+  #     #   [-4, -1.5874010519682, -4.0]
+  #     #   [-3, -1.44224957030741, -3.0]
+  #     #   [-2, -1.25992104989487, -2.0]
+  #     #   [-1, -1.0, -1.0]
+  #     #   [0, 0.0, 0.0]
+  #     #   [1, 1.0, 1.0]
+  #     #   [2, 1.25992104989487, 2.0]
+  #     #   [3, 1.44224957030741, 3.0]
+  #     #   [4, 1.5874010519682, 4.0]
+  #     #   [5, 1.7099759466767, 5.0]
+  #     #   [6, 1.81712059283214, 6.0]
+  #     #   [7, 1.91293118277239, 7.0]
+  #     #   [8, 2.0, 8.0]
+  #     #   [9, 2.0800838230519, 9.0]
+  #
   def self.cbrt: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the cosine of `x` (expressed in radians). Returns a Float in the
+  # range -1.0..1.0.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: [-1, 1]
+  #
+  #     Math.cos(Math::PI) #=> -1.0
+  #
   def self.cos: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the hyperbolic cosine of `x` (expressed in radians).
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: [1, INFINITY)
+  #
+  #     Math.cosh(0) #=> 1.0
+  #
   def self.cosh: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Calculates the error function of `x`.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-1, 1)
+  #
+  #     Math.erf(0) #=> 0.0
+  #
   def self.erf: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Calculates the complementary error function of x.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (0, 2)
+  #
+  #     Math.erfc(0) #=> 1.0
+  #
   def self.erfc: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Returns e**x.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (0, INFINITY)
+  #
+  #     Math.exp(0)       #=> 1.0
+  #     Math.exp(1)       #=> 2.718281828459045
+  #     Math.exp(1.5)     #=> 4.4816890703380645
+  #
   def self.exp: (Integer | Float | Rational | BigDecimal x) -> Float
 
-  def self.frexp: (Integer | Float | Rational | BigDecimal x) -> [ Integer | Float | Rational | BigDecimal, Integer | Float | Rational | BigDecimal ]
+  # Returns a two-element array containing the normalized fraction (a Float) and
+  # exponent (an Integer) of `x`.
+  #
+  #     fraction, exponent = Math.frexp(1234)   #=> [0.6025390625, 11]
+  #     fraction * 2**exponent                  #=> 1234.0
+  #
+  def self.frexp: (Integer | Float | Rational | BigDecimal x) -> [ Float, Integer ]
 
+  # Calculates the gamma function of x.
+  #
+  # Note that gamma(n) is same as fact(n-1) for integer n > 0. However gamma(n)
+  # returns float and can be an approximation.
+  #
+  #     def fact(n) (1..n).inject(1) {|r,i| r*i } end
+  #     1.upto(26) {|i| p [i, Math.gamma(i), fact(i-1)] }
+  #     #=> [1, 1.0, 1]
+  #     #   [2, 1.0, 1]
+  #     #   [3, 2.0, 2]
+  #     #   [4, 6.0, 6]
+  #     #   [5, 24.0, 24]
+  #     #   [6, 120.0, 120]
+  #     #   [7, 720.0, 720]
+  #     #   [8, 5040.0, 5040]
+  #     #   [9, 40320.0, 40320]
+  #     #   [10, 362880.0, 362880]
+  #     #   [11, 3628800.0, 3628800]
+  #     #   [12, 39916800.0, 39916800]
+  #     #   [13, 479001600.0, 479001600]
+  #     #   [14, 6227020800.0, 6227020800]
+  #     #   [15, 87178291200.0, 87178291200]
+  #     #   [16, 1307674368000.0, 1307674368000]
+  #     #   [17, 20922789888000.0, 20922789888000]
+  #     #   [18, 355687428096000.0, 355687428096000]
+  #     #   [19, 6.402373705728e+15, 6402373705728000]
+  #     #   [20, 1.21645100408832e+17, 121645100408832000]
+  #     #   [21, 2.43290200817664e+18, 2432902008176640000]
+  #     #   [22, 5.109094217170944e+19, 51090942171709440000]
+  #     #   [23, 1.1240007277776077e+21, 1124000727777607680000]
+  #     #   [24, 2.5852016738885062e+22, 25852016738884976640000]
+  #     #   [25, 6.204484017332391e+23, 620448401733239439360000]
+  #     #   [26, 1.5511210043330954e+25, 15511210043330985984000000]
+  #
   def self.gamma: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle with
+  # sides `x` and `y`.
+  #
+  #     Math.hypot(3, 4)   #=> 5.0
+  #
   def self.hypot: (Integer | Float | Rational | BigDecimal x, Integer | Float | Rational | BigDecimal y) -> Float
 
+  # Returns the value of `fraction`*(2**`exponent`).
+  #
+  #     fraction, exponent = Math.frexp(1234)
+  #     Math.ldexp(fraction, exponent)   #=> 1234.0
+  #
   def self.ldexp: (Integer | Float | Rational | BigDecimal fraction, Integer | Float | Rational | BigDecimal exponent) -> Float
 
-  def self.lgamma: (Integer | Float | Rational | BigDecimal x) -> (Integer | Float)
+  # Calculates the logarithmic gamma of `x` and the sign of gamma of `x`.
+  #
+  # Math.lgamma(x) is same as
+  #     [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
+  #
+  # but avoid overflow by Math.gamma(x) for large x.
+  #
+  #     Math.lgamma(0) #=> [Infinity, 1]
+  #
+  def self.lgamma: (Integer | Float | Rational | BigDecimal x) -> [ Float, Integer ]
 
   def self.log: (Integer | Float | Rational | BigDecimal x, ?Integer | Float | Rational | BigDecimal base) -> Float
 
+  # Returns the base 10 logarithm of `x`.
+  #
+  # Domain: (0, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.log10(1)       #=> 0.0
+  #     Math.log10(10)      #=> 1.0
+  #     Math.log10(10**100) #=> 100.0
+  #
   def self.log10: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Returns the base 2 logarithm of `x`.
+  #
+  # Domain: (0, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.log2(1)      #=> 0.0
+  #     Math.log2(2)      #=> 1.0
+  #     Math.log2(32768)  #=> 15.0
+  #     Math.log2(65536)  #=> 16.0
+  #
   def self.log2: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the sine of `x` (expressed in radians). Returns a Float in the range
+  # -1.0..1.0.
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: [-1, 1]
+  #
+  #     Math.sin(Math::PI/2) #=> 1.0
+  #
   def self.sin: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the hyperbolic sine of `x` (expressed in radians).
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.sinh(0) #=> 0.0
+  #
   def self.sinh: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Returns the non-negative square root of `x`.
+  #
+  # Domain: [0, INFINITY)
+  #
+  # Codomain:[0, INFINITY)
+  #
+  #     0.upto(10) {|x|
+  #       p [x, Math.sqrt(x), Math.sqrt(x)**2]
+  #     }
+  #     #=> [0, 0.0, 0.0]
+  #     #   [1, 1.0, 1.0]
+  #     #   [2, 1.4142135623731, 2.0]
+  #     #   [3, 1.73205080756888, 3.0]
+  #     #   [4, 2.0, 4.0]
+  #     #   [5, 2.23606797749979, 5.0]
+  #     #   [6, 2.44948974278318, 6.0]
+  #     #   [7, 2.64575131106459, 7.0]
+  #     #   [8, 2.82842712474619, 8.0]
+  #     #   [9, 3.0, 9.0]
+  #     #   [10, 3.16227766016838, 10.0]
+  #
+  # Note that the limited precision of floating point arithmetic might lead to
+  # surprising results:
+  #
+  #     Math.sqrt(10**46).to_i  #=> 99999999999999991611392 (!)
+  #
+  # See also BigDecimal#sqrt and Integer.sqrt.
+  #
   def self.sqrt: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the tangent of `x` (expressed in radians).
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.tan(0) #=> 0.0
+  #
   def self.tan: (Integer | Float | Rational | BigDecimal x) -> Float
 
+  # Computes the hyperbolic tangent of `x` (expressed in radians).
+  #
+  # Domain: (-INFINITY, INFINITY)
+  #
+  # Codomain: (-1, 1)
+  #
+  #     Math.tanh(0) #=> 0.0
+  #
   def self.tanh: (Integer | Float | Rational | BigDecimal x) -> Float
 end
 
+# Definition of the mathematical constant E for Euler's number (e) as a Float
+# number.
+#
+#
 Math::E: Float
 
+# Definition of the mathematical constant PI as a Float number.
+#
+#
 Math::PI: Float
 
+# Raised when a mathematical function is evaluated outside of its domain of
+# definition.
+#
+# For example, since `cos` returns values in the range -1..1, its inverse
+# function `acos` is only defined on that interval:
+#
+#     Math.acos(42)
+#
+# *produces:*
+#
+#     Math::DomainError: Numerical argument is out of domain - "acos"
+#
 class Math::DomainError < StandardError
 end