From 539409f9366502a8e418a07d013886628c5dcbcb Mon Sep 17 00:00:00 2001
From: Sandor Szuecs <sandor.szuecs@fu-berlin.de>
Date: Mon, 16 May 2011 20:01:14 +0200
Subject: [PATCH 2/2] cmath doc


Signed-off-by: Sandor Szuecs <sandor.szuecs@fu-berlin.de>
---
 lib/cmath.rb |   46 +++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/lib/cmath.rb b/lib/cmath.rb
index 8a47b5f..49bdce9 100644
--- a/lib/cmath.rb
+++ b/lib/cmath.rb
@@ -1,8 +1,17 @@
-# This module provides access to mathematical functions for complex
-# numbers.
-# 
-# Example 
-#   # Square root of a negative number is a complex number.
+##
+# = CMath
+#
+# CMath is a library that provides trigonometric and transcendental
+# functions for complex numbers.
+#
+# == Usage
+#
+# To start using this library, simply:
+#
+#   require "cmath"
+#
+# Square root of a negative number is a complex number.
+#
 #   CMath.sqrt(-9)  #=> 0+3.0i
 #
 module CMath
@@ -33,6 +42,10 @@ module CMath
   alias acosh! acosh
   alias atanh! atanh
 
+  # Returns e**z. 
+  #   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
   def exp(z)
     if z.real?
       exp!(z)
@@ -43,6 +56,9 @@ module CMath
     end
   end
 
+  # Returns the natural logarithm of Complex. If additional second
+  # argument is given, it will be the base of logarithm.
+  #   log(Complex(0,0)) #=> -Infinity+0.0i
   def log(*args)
     z, b = args
     if z.real? and z >= 0 and (b.nil? or b >= 0)
@@ -56,6 +72,7 @@ module CMath
     end
   end
 
+  # Returns the base 2 logarithm of Complex. 
   def log2(z)
     if z.real? and z >= 0
       log2!(z)
@@ -64,6 +81,7 @@ module CMath
     end
   end
 
+  # Returns the base 10 logarithm of Complex. 
   def log10(z)
     if z.real? and z >= 0
       log10!(z)
@@ -72,6 +90,10 @@ module CMath
     end
   end
 
+  # 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
   def sqrt(z)
     if z.real?
       if z < 0
@@ -91,6 +113,7 @@ module CMath
     end
   end
 
+  # Returns the cube root of a Complex. 
   def cbrt(z)
     if z.real?
       cbrt!(z)
@@ -99,6 +122,7 @@ module CMath
     end
   end
 
+  # Computes the sine of z (expressed in radians). 
   def sin(z)
     if z.real?
       sin!(z)
@@ -108,6 +132,7 @@ module CMath
     end
   end
 
+  # Computes the cosine of z (expressed in radians).
   def cos(z)
     if z.real?
       cos!(z)
@@ -117,6 +142,7 @@ module CMath
     end
   end
 
+  # Returns the tangent of z (expressed in radians).
   def tan(z)
     if z.real?
       tan!(z)
@@ -125,6 +151,7 @@ module CMath
     end
   end
 
+  # Computes the hyperbolic sine of z (expressed in radians).
   def sinh(z)
     if z.real?
       sinh!(z)
@@ -134,6 +161,7 @@ module CMath
     end
   end
 
+  # Computes the hyperbolic cosine of z (expressed in radians).
   def cosh(z)
     if z.real?
       cosh!(z)
@@ -143,6 +171,7 @@ module CMath
     end
   end
 
+  # Computes the hyperbolic tangent of z (expressed in radians).
   def tanh(z)
     if z.real?
       tanh!(z)
@@ -151,6 +180,7 @@ module CMath
     end
   end
 
+  # Computes the arc sine of z.
   def asin(z)
     if z.real? and z >= -1 and z <= 1
       asin!(z)
@@ -159,6 +189,7 @@ module CMath
     end
   end
 
+  # Computes the arc cosine of z. 
   def acos(z)
     if z.real? and z >= -1 and z <= 1
       acos!(z)
@@ -167,6 +198,7 @@ module CMath
     end
   end
 
+  # Computes the arc tangent of z.
   def atan(z)
     if z.real?
       atan!(z)
@@ -175,6 +207,7 @@ module CMath
     end
   end
 
+  # Computes the arc tangent given y and x.
   def atan2(y,x)
     if y.real? and x.real?
       atan2!(y,x)
@@ -183,6 +216,7 @@ module CMath
     end
   end
 
+  # Computes the inverse hyperbolic sine of z.
   def asinh(z)
     if z.real?
       asinh!(z)
@@ -191,6 +225,7 @@ module CMath
     end
   end
 
+  # Computes the inverse hyperbolic cosine of z.
   def acosh(z)
     if z.real? and z >= 1
       acosh!(z)
@@ -199,6 +234,7 @@ module CMath
     end
   end
 
+  # Computes the inverse hyperbolic tangent of z.
   def atanh(z)
     if z.real? and z >= -1 and z <= 1
       atanh!(z)
-- 
1.7.5.1