1 files changed, 56 insertions, 15 deletions

diff --git a/ext/bigdecimal/lib/bigdecimal/math.rb b/ext/bigdecimal/lib/bigdecimal/math.rb
index 7289661fc2..4504ccb2b0 100644
--- a/ext/bigdecimal/lib/bigdecimal/math.rb
+++ b/ext/bigdecimal/lib/bigdecimal/math.rb
@@ -20,30 +20,40 @@ require 'bigdecimal'
 #
 # Example:
 #
-#   require "bigdecimal"
 #   require "bigdecimal/math"
 #
 #   include BigMath
 #
 #   a = BigDecimal((PI(100)/2).to_s)
-#   puts sin(a,100) # -> 0.10000000000000000000......E1
+#   puts sin(a,100) # => 0.10000000000000000000......E1
 #
 module BigMath
   module_function
 
-  # Computes the square root of x to the specified number of digits of
-  # precision.
+  # call-seq:
+  #   sqrt(decimal, numeric) -> BigDecimal
   #
-  # BigDecimal.new('2').sqrt(16).to_s
-  #  -> "0.14142135623730950488016887242096975E1"
+  # Computes the square root of +decimal+ to the specified number of digits of
+  # precision, +numeric+.
   #
-  def sqrt(x,prec)
+  #   BigMath::sqrt(BigDecimal.new('2'), 16).to_s
+  #   #=> "0.14142135623730950488016887242096975E1"
+  #
+  def sqrt(x, prec)
     x.sqrt(prec)
   end
 
-  # Computes the sine of x to the specified number of digits of precision.
+  # call-seq:
+  #   sin(decimal, numeric) -> BigDecimal
+  #
+  # Computes the sine of +decimal+ to the specified number of digits of
+  # precision, +numeric+.
+  #
+  # If +decimal+ is Infinity or NaN, returns NaN.
+  #
+  #   BigMath::sin(BigMath::PI(5)/4, 5).to_s
+  #   #=> "0.70710678118654752440082036563292800375E0"
   #
-  # If x is infinite or NaN, returns NaN.
   def sin(x, prec)
     raise ArgumentError, "Zero or negative precision for sin" if prec <= 0
     return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -77,9 +87,17 @@ module BigMath
     neg ? -y : y
   end
 
-  # Computes the cosine of x to the specified number of digits of precision.
+  # call-seq:
+  #   cos(decimal, numeric) -> BigDecimal
+  #
+  # Computes the cosine of +decimal+ to the specified number of digits of
+  # precision, +numeric+.
+  #
+  # If +decimal+ is Infinity or NaN, returns NaN.
+  #
+  #   BigMath::cos(BigMath::PI(4), 16).to_s
+  #   #=> "-0.999999999999999999999999999999856613163740061349E0"
   #
-  # If x is infinite or NaN, returns NaN.
   def cos(x, prec)
     raise ArgumentError, "Zero or negative precision for cos" if prec <= 0
     return BigDecimal("NaN") if x.infinite? || x.nan?
@@ -113,9 +131,17 @@ module BigMath
     y
   end
 
-  # Computes the arctangent of x to the specified number of digits of precision.
+  # call-seq:
+  #   atan(decimal, numeric) -> BigDecimal
+  #
+  # Computes the arctangent of +decimal+ to the specified number of digits of
+  # precision, +numeric+.
+  #
+  # If +decimal+ is NaN, returns NaN.
+  #
+  #   BigMath::atan(BigDecimal.new('-1'), 16).to_s
+  #   #=> "-0.785398163397448309615660845819878471907514682065E0"
   #
-  # If x is NaN, returns NaN.
   def atan(x, prec)
     raise ArgumentError, "Zero or negative precision for atan" if prec <= 0
     return BigDecimal("NaN") if x.nan?
@@ -144,7 +170,15 @@ module BigMath
     y
   end
 
-  # Computes the value of pi to the specified number of digits of precision.
+  # call-seq:
+  #   PI(numeric) -> BigDecimal
+  #
+  # Computes the value of pi to the specified number of digits of precision,
+  # +numeric+.
+  #
+  #   BigMath::PI(10).to_s
+  #   #=> "0.3141592653589793238462643388813853786957412E1"
+  #
   def PI(prec)
     raise ArgumentError, "Zero or negative argument for PI" if prec <= 0
     n      = prec + BigDecimal.double_fig
@@ -181,8 +215,15 @@ module BigMath
     pi
   end
 
+  # call-seq:
+  #   E(numeric) -> BigDecimal
+  #
   # Computes e (the base of natural logarithms) to the specified number of
-  # digits of precision.
+  # digits of precision, +numeric+.
+  #
+  #   BigMath::E(10).to_s
+  #   #=> "0.271828182845904523536028752390026306410273E1"
+  #
   def E(prec)
     raise ArgumentError, "Zero or negative precision for E" if prec <= 0
     n    = prec + BigDecimal.double_fig