* ext/bigdecimal/lib/bigdecimal/util.rb: Improve documentation. Patch

	  by Pete Higgins.  [Ruby 1.9 - Bug #4746]


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

1 files changed, 45 insertions, 18 deletions

diff --git a/ext/bigdecimal/lib/bigdecimal/util.rb b/ext/bigdecimal/lib/bigdecimal/util.rb
index a0235460bd..6d22d2785d 100644
--- a/ext/bigdecimal/lib/bigdecimal/util.rb
+++ b/ext/bigdecimal/lib/bigdecimal/util.rb
@@ -1,35 +1,50 @@
-#
-# BigDecimal utility library.
-#
-# To use these functions, require 'bigdecimal/util'
-#
-# The following methods are provided to convert other types to BigDecimals:
-#
-#   String#to_d -> BigDecimal
-#   Float#to_d -> BigDecimal
-#   Rational#to_d -> BigDecimal
-#
-# The following method is provided to convert BigDecimals to other types:
-#
-#   BigDecimal#to_r -> Rational
-#
-# ----------------------------------------------------------------------
-#
 class Float < Numeric
+  # call-seq:
+  #     flt.to_d  -> bigdecimal
+  #
+  # Convert +flt+ to a BigDecimal and return it.
+  #
+  #     require 'bigdecimal'
+  #     require 'bigdecimal/util'
+  #
+  #     0.5.to_d
+  #     # => #<BigDecimal:1dc69e0,'0.5E0',9(18)> 
+  #
   def to_d
     BigDecimal(self.to_s)
   end
 end
 
 class String
+  # call-seq:
+  #     string.to_d  -> bigdecimal
+  #
+  # Convert +string+ to a BigDecimal and return it.
+  #
+  #     require 'bigdecimal'
+  #     require 'bigdecimal/util'
+  #
+  #     "0.5".to_d
+  #     # => #<BigDecimal:1dc69e0,'0.5E0',9(18)> 
+  #
   def to_d
     BigDecimal(self)
   end
 end
 
 class BigDecimal < Numeric
+  # call-seq:
+  #     a.to_digits -> string
+  #
   # Converts a BigDecimal to a String of the form "nnnnnn.mmm".
   # This method is deprecated; use BigDecimal#to_s("F") instead.
+  #
+  #     require 'bigdecimal'
+  #     require 'bigdecimal/util'
+  #
+  #     d = BigDecimal.new("3.14")
+  #     d.to_digits
+  #     # => "3.14"
   def to_digits
     if self.nan? || self.infinite? || self.zero?
       self.to_s
@@ -42,7 +57,19 @@ class BigDecimal < Numeric
 end
 
 class Rational < Numeric
-  # Converts a Rational to a BigDecimal
+  # call-seq:
+  #   r.to_d        -> bigdecimal
+  #   r.to_d(sig)   -> bigdecimal
+  #
+  # Converts a Rational to a BigDecimal. Takes an optional parameter +sig+ to
+  # limit the amount of significant digits.
+  #
+  #   r = (22/7.0).to_r
+  #   # => (7077085128725065/2251799813685248)
+  #   r.to_d
+  #   # => #<BigDecimal:1a52bd8,'0.3142857142 8571427937 0154144999 105E1',45(63)>
+  #   r.to_d(3)
+  #   # => #<BigDecimal:1a44d08,'0.314E1',18(36)> 
   def to_d(nFig=0)
     num = self.numerator.to_s
     if nFig<=0