ruby · davydovanton · May 19, 2015
diff --git a/complex.c b/complex.c
@@ -2112,6 +2112,29 @@ float_arg(VALUE self)
  *
  *    Complex(1, 1) / 2    #=> ((1/2)+(1/2)*i)
  *    Complex(1, 1) / 2.0  #=> (0.5+0.5i)
+ *
+ * == Brief overview of complex numbers
+ *
+ * A complex number is a number that can be expressed in the form
+ * a + bi, where a and b are real numbers and i is the imaginary unit,
+ * that satisfies the equation x**2 = −1, that is, i**2 = −1. In this
+ * expression, a is the real part and b is the imaginary part of the
+ * complex number.
+ *
+ * In ruby, you can create complex object with Complex, ::rect, ::polar
+ * or #to_c method.
+ *
+ *   Complex(1)             #=> (1+0i)
+ *   1 + 1i                 #=> (1+1i)
+ *   Complex.polar(2, 3)    #=> (-1.9799849932008908+0.2822400161197344i)
+ *   3.to_c                 #=> (3+0i)
+ *
+ * == References
+ *
+ * Kahan, W: Branch cuts for complex elementary functions
+ * Solomentsev, E.D. (2001), "Complex number", in Hazewinkel, Michiel,
+ * <em>Encyclopedia of Mathematics, Springer, ISBN 978-1-55608-010-4
+ *
  */
 void
 Init_Complex(void)

diff --git a/lib/cmath.rb b/lib/cmath.rb
@@ -1,17 +1,30 @@
 ##
+# = Trigonometric and transcendental functions for complex numbers.
+#
 # CMath is a library that provides trigonometric and transcendental
-# functions for complex numbers.
+# functions for complex numbers. The functions in this module accept
+# integers, floating-point numbers or complex numbers as arguments.
+#
+# Note that the selection of functions is similar, but not identical,
+# to that in module math. The reason for having two modules is that
+# some users aren’t interested in complex numbers, and perhaps don’t
+# even know what they are. They would rather have Math.sqrt(-1) raise
+# an exception than return a complex number.
 #
 # == Usage
 #
-# To start using this library, simply:
+# To start using this library, simply require cmath library:
 #
 #   require "cmath"
 #
-# Square root of a negative number is a complex number.
+# And after call any CMath function. For example:
+#
+#   CMath.sqrt(-9)          #=> 0+3.0i
+#   CMath.exp(0 + 0i)       #=> 1.0+0.0i
+#   CMath.log10(-5.to_c)    #=> (0.6989700043360187+1.3643763538418412i)
 #
-#   CMath.sqrt(-9)  #=> 0+3.0i
 #
+# For more information you can see Complec class.
 
 module CMath
 
@@ -44,9 +57,7 @@ module CMath
   ##
   # Math::E raised to the +z+ power
   #
-  #   exp(Complex(0,0))      #=> 1.0+0.0i
-  #   exp(Complex(0,PI))     #=> -1.0+1.2246467991473532e-16i
-  #   exp(Complex(0,PI/2.0)) #=> 6.123233995736766e-17+1.0i
+  #   CMath.exp(2i) #=> (-0.4161468365471424+0.9092974268256817i)
   def exp(z)
     begin
       if z.real?
@@ -62,10 +73,11 @@ def exp(z)
   end
 
   ##
-  # Returns the natural logarithm of Complex.  If a second argument is given,
+  # Returns the natural logarithm of Complex. If a second argument is given,
   # it will be the base of logarithm.
   #
-  #   log(Complex(0,0)) #=> -Infinity+0.0i
+  #   CMath.log(1 + 4i)     #=> (1.416606672028108+1.3258176636680326i)
+  #   CMath.log(1 + 4i, 10) #=> (0.6152244606891369+0.5757952953408879i)
   def log(z, b=::Math::E)
     begin
       if z.real? && z >= 0 && b >= 0
@@ -80,6 +92,8 @@ def log(z, b=::Math::E)
 
   ##
   # returns the base 2 logarithm of +z+
+  #
+  #   CMath.log2(-1) => (0.0+4.532360141827194i)
   def log2(z)
     begin
       if z.real? and z >= 0
@@ -94,6 +108,8 @@ def log2(z)
 
   ##
   # returns the base 10 logarithm of +z+
+  #
+  #   CMath.log10(-1) #=> (0.0+1.3643763538418412i)
   def log10(z)
     begin
       if z.real? and z >= 0
@@ -108,9 +124,8 @@ def log10(z)
 
   ##
   # Returns the non-negative square root of Complex.
-  #   sqrt(-1)            #=> 0+1.0i
-  #   sqrt(Complex(-1,0)) #=> 0.0+1.0i
-  #   sqrt(Complex(0,8))  #=> 2.0+2.0i
+  #
+  #   CMath.sqrt(-1 + 0i) #=> 0.0+1.0i
   def sqrt(z)
     begin
       if z.real?
@@ -136,12 +151,16 @@ def sqrt(z)
 
   ##
   # returns the principal value of the cube root of +z+
+  #
+  #   CMath.cbrt(1 + 4i) #=> (1.449461632813119+0.6858152562177092i)
   def cbrt(z)
     z ** (1.0/3)
   end
 
   ##
   # returns the sine of +z+, where +z+ is given in radians
+  #
+  #   CMath.sin(1 + 1i) #=> (1.2984575814159773+0.6349639147847361i)
   def sin(z)
     begin
       if z.real?
@@ -157,6 +176,8 @@ def sin(z)
 
   ##
   # returns the cosine of +z+, where +z+ is given in radians
+  #
+  #   CMath.cos(1 + 1i) #=> (0.8337300251311491-0.9888977057628651i)
   def cos(z)
     begin
       if z.real?
@@ -172,6 +193,8 @@ def cos(z)
 
   ##
   # returns the tangent of +z+, where +z+ is given in radians
+  #
+  #   CMath.tan(1 + 1i) #=> (0.27175258531951174+1.0839233273386943i)
   def tan(z)
     begin
       if z.real?
@@ -186,6 +209,8 @@ def tan(z)
 
   ##
   # returns the hyperbolic sine of +z+, where +z+ is given in radians
+  #
+  #   CMath.sinh(1 + 1i) #=> (0.6349639147847361+1.2984575814159773i)
   def sinh(z)
     begin
       if z.real?
@@ -201,6 +226,8 @@ def sinh(z)
 
   ##
   # returns the hyperbolic cosine of +z+, where +z+ is given in radians
+  #
+  #   CMath.cosh(1 + 1i) #=> (0.8337300251311491+0.9888977057628651i)
   def cosh(z)
     begin
       if z.real?
@@ -216,6 +243,8 @@ def cosh(z)
 
   ##
   # returns the hyperbolic tangent of +z+, where +z+ is given in radians
+  #
+  #   CMath.tanh(1 + 1i) #=> (1.0839233273386943+0.27175258531951174i)
   def tanh(z)
     begin
       if z.real?
@@ -230,6 +259,8 @@ def tanh(z)
 
   ##
   # returns the arc sine of +z+
+  #
+  #   CMath.asin(1 + 1i) #=> (0.6662394324925153+1.0612750619050355i)
   def asin(z)
     begin
       if z.real? and z >= -1 and z <= 1
@@ -244,6 +275,8 @@ def asin(z)
 
   ##
   # returns the arc cosine of +z+
+  #
+  #   CMath.acos(1 + 1i) #=> (0.9045568943023813-1.0612750619050357i)
   def acos(z)
     begin
       if z.real? and z >= -1 and z <= 1
@@ -258,6 +291,8 @@ def acos(z)
 
   ##
   # returns the arc tangent of +z+
+  #
+  #   CMath.atan(1 + 1i) #=> (1.0172219678978514+0.4023594781085251i)
   def atan(z)
     begin
       if z.real?
@@ -273,6 +308,8 @@ def atan(z)
   ##
   # returns the arc tangent of +y+ divided by +x+ using the signs of +y+ and
   # +x+ to determine the quadrant
+  #
+  #   CMath.atan2(1 + 1i, 0) #=> (1.5707963267948966+0.0i)
   def atan2(y,x)
     begin
       if y.real? and x.real?
@@ -287,6 +324,8 @@ def atan2(y,x)
 
   ##
   # returns the inverse hyperbolic sine of +z+
+  #
+  #   CMath.asinh(1 + 1i) #=> (1.0612750619050357+0.6662394324925153i)
   def asinh(z)
     begin
       if z.real?
@@ -301,6 +340,8 @@ def asinh(z)
 
   ##
   # returns the inverse hyperbolic cosine of +z+
+  #
+  #   CMath.acosh(1 + 1i) #=> (1.0612750619050357+0.9045568943023813i)
   def acosh(z)
     begin
       if z.real? and z >= 1
@@ -315,6 +356,8 @@ def acosh(z)
 
   ##
   # returns the inverse hyperbolic tangent of +z+
+  #
+  #   CMath.atanh(1 + 1i) #=> (0.4023594781085251+1.0172219678978514i)
   def atanh(z)
     begin
       if z.real? and z >= -1 and z <= 1