* lib/cmath.rb: [DOC] Add docs [ci skip][Fix GH-909][Bug #11162]

Patch provided by @davydovanton

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@50793 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

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.sqrt(-9)          #=> 0+3.0i
+#   CMath.exp(0 + 0i)       #=> 1.0+0.0i
+#   CMath.log10(-5.to_c)    #=> (0.6989700043360187+1.3643763538418412i)
 #
+#
+# 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 @@ module CMath
   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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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 @@ module CMath
 
   ##
   # 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