Improve documentation of mathematical functions (#9994)

src/big/big_float.cr

@@ -355,6 +355,7 @@ class String
 end
 
 module Math
+  # Decomposes the given floating-point *value* into a normalized fraction and an integral power of two.
   def frexp(value : BigFloat)
     LibGMP.mpf_get_d_2exp(out exp, value) # we need BigFloat frac, so will skip Float64 one.
     frac = BigFloat.new do |mpf|
@@ -367,11 +368,12 @@ module Math
     {frac, exp}
   end
 
-  # Returns the sqrt of a `BigFloat`.
+  # Calculates the square root of *value*.
   #
   # ```
   # require "big"
-  # Math.sqrt((1000_000_000_0000.to_big_f*1000_000_000_00000.to_big_f))
+  #
+  # Math.sqrt(1_000_000_000_000.to_big_f * 1_000_000_000_000.to_big_f) # => 1000000000000.0
   # ```
   def sqrt(value : BigFloat)
     BigFloat.new { |mpf| LibGMP.mpf_sqrt(mpf, value) }

src/big/big_int.cr

@@ -720,12 +720,12 @@ class String
 end
 
 module Math
-  # Returns the sqrt of a `BigInt`.
+  # Calculates the square root of *value*.
   #
   # ```
   # require "big"
   #
-  # Math.sqrt((1000_000_000_0000.to_big_i*1000_000_000_00000.to_big_i))
+  # Math.sqrt(1_000_000_000_000.to_big_i * 1_000_000_000_000.to_big_i) # => 1000000000000.0
   # ```
   def sqrt(value : BigInt)
     sqrt(value.to_big_f)

src/big/big_rational.cr

@@ -345,11 +345,12 @@ struct Float
 end
 
 module Math
-  # Returns the sqrt of a `BigRational`.
+  # Calculates the square root of *value*.
+  #
   # ```
   # require "big"
   #
-  # Math.sqrt((1000_000_000_0000.to_big_r*1000_000_000_00000.to_big_r))
+  # Math.sqrt(1_000_000_000_000.to_big_r * 1_000_000_000_000.to_big_r) # => 1000000000000.0
   # ```
   def sqrt(value : BigRational)
     sqrt(value.to_big_f)

src/complex.cr

@@ -296,52 +296,52 @@ struct Number
 end
 
 module Math
-  # Calculates the exponential of the complex number `z`.
+  # Calculates the exponential of *value*.
   #
   # ```
   # require "complex"
   #
   # Math.exp(4 + 2.i) # => -22.720847417619233 + 49.645957334580565i
   # ```
-  def exp(z : Complex)
-    r = exp(z.real)
-    Complex.new(r * cos(z.imag), r * sin(z.imag))
+  def exp(value : Complex)
+    r = exp(value.real)
+    Complex.new(r * cos(value.imag), r * sin(value.imag))
   end
 
-  # Calculates the natural logarithm of the complex number `z`.
+  # Calculates the natural logarithm of *value*.
   #
   # ```
   # require "complex"
   #
   # Math.log(4 + 2.i) # => 1.4978661367769956 + 0.4636476090008061i
   # ```
-  def log(z : Complex)
-    Complex.new(Math.log(z.abs), z.phase)
+  def log(value : Complex)
+    Complex.new(Math.log(value.abs), value.phase)
   end
 
-  # Calculates the base-2 logarithm of the complex number `z`.
+  # Calculates the logarithm of *value* to base 2.
   #
   # ```
   # require "complex"
   #
   # Math.log2(4 + 2.i) # => 2.1609640474436813 + 0.6689021062254881i
   # ```
-  def log2(z : Complex)
-    log(z) / LOG2
+  def log2(value : Complex)
+    log(value) / LOG2
   end
 
-  # Calculates the base-10 logarithm of the complex number `z`.
+  # Calculates the logarithm of *value* to base 10.
   #
   # ```
   # require "complex"
   #
   # Math.log10(4 + 2.i) # => 0.6505149978319906 + 0.20135959813668655i
   # ```
-  def log10(z : Complex)
-    log(z) / LOG10
+  def log10(value : Complex)
+    log(value) / LOG10
   end
 
-  # Calculates the square root of the complex number `z`.
+  # Calculates the square root of *value*.
   # Inspired by the [following blog post](https://pavpanchekha.com/blog/casio-mathjs.html) of Pavel Panchekha on floating point precision.
   #
   # ```
@@ -359,21 +359,21 @@ module Math
   # Math.sqrt(-1.0)         # => -NaN
   # Math.sqrt(-1.0 + 0.0.i) # => 0.0 + 1.0i
   # ```
-  def sqrt(z : Complex)
-    r = z.abs
+  def sqrt(value : Complex)
+    r = value.abs
 
-    re = if z.real >= 0
-           0.5 * sqrt(2.0 * (r + z.real))
+    re = if value.real >= 0
+           0.5 * sqrt(2.0 * (r + value.real))
          else
-           z.imag.abs / sqrt(2.0 * (r - z.real))
+           value.imag.abs / sqrt(2.0 * (r - value.real))
          end
 
-    im = if z.real <= 0
-           0.5 * sqrt(2.0 * (r - z.real))
+    im = if value.real <= 0
+           0.5 * sqrt(2.0 * (r - value.real))
          else
-           z.imag.abs / sqrt(2.0 * (r + z.real))
+           value.imag.abs / sqrt(2.0 * (r + value.real))
          end
 
-    Complex.new(re, z.imag >= 0 ? im : -im)
+    Complex.new(re, value.imag >= 0 ? im : -im)
   end
 end