merge revision(s) 50793,51120: [Backport #11162]

	* 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/branches/ruby_2_1@51121 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 56 insertions, 14 deletions

diff --git a/lib/cmath.rb b/lib/cmath.rb
index 337c2e063a..24d619fe75 100644
--- 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 @@ 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(*args)
     begin
       z, b = args
@@ -88,6 +100,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
@@ -102,6 +116,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
@@ -116,9 +132,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?
@@ -144,12 +159,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?
@@ -165,6 +184,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?
@@ -180,6 +201,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?
@@ -194,6 +217,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?
@@ -209,6 +234,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?
@@ -224,6 +251,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?
@@ -238,6 +267,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
@@ -252,6 +283,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
@@ -266,6 +299,8 @@ module CMath
 
   ##
   # returns the arc tangent of +z+
+  #
+  #   CMath.atan(1 + 1i) #=> (1.0172219678978514+0.4023594781085251i)
   def atan(z)
     begin
       if z.real?
@@ -281,6 +316,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?
@@ -295,6 +332,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?
@@ -309,6 +348,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
@@ -323,6 +364,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
@@ -397,4 +440,3 @@ module CMath
   module_function :handle_no_method_error
 
 end
-
diff --git a/version.h b/version.h
index 29dac215d9..50b6cbad60 100644
--- a/version.h
+++ b/version.h
@@ -1,6 +1,6 @@
 #define RUBY_VERSION "2.1.7"
 #define RUBY_RELEASE_DATE "2015-07-03"
-#define RUBY_PATCHLEVEL 371
+#define RUBY_PATCHLEVEL 372
 
 #define RUBY_RELEASE_YEAR 2015
 #define RUBY_RELEASE_MONTH 7