money 3.1.0.pre3 → 3.1.0

data/lib/money/bank/variable_exchange.rb

@@ -1,44 +1,77 @@
 require 'money/bank/base'
-require 'json'
-require 'yaml'
+autoload :JSON, 'json'
+autoload :YAML, 'yaml'
 
 class Money
   module Bank
-    # Thrown by VariableExchange#export_rates and VariableExchange#import_rates
-    # when an unknown rate format is requested.
+    # Thrown when an unknown rate format is requested.
     class UnknownRateFormat < StandardError; end
 
-    # Class for aiding in exchanging money between different currencies.
-    # By default, the Money class uses an object of this class (accessible through
-    # Money#bank) for performing currency exchanges.
+    # Class for aiding in exchanging money between different currencies. By
+    # default, the +Money+ class uses an object of this class (accessible
+    # through +Money#bank+) for performing currency exchanges.
     #
-    # By default, Bank::VariableExchange has no knowledge about conversion rates.
-    # One must manually specify them with +add_rate+, after which one can perform
-    # exchanges with +exchange+. For example:
+    # By default, +Money::Bank::VariableExchange+ has no knowledge about
+    # conversion rates. One must manually specify them with +add_rate+, after
+    # which one can perform exchanges with +#exchange_with+.
     #
+    # @example
     #   bank = Money::Bank::VariableExchange.new
     #   bank.add_rate("USD", "CAD", 1.24515)
     #   bank.add_rate("CAD", "USD", 0.803115)
     #
-    #   # Exchange 100 CAD to USD:
-    #   bank.exchange(100_00, "CAD", "USD")  # => 124
+    #   c1 = 100_00.to_money("USD")
+    #   c2 = 100_00.to_money("CAD")
+    #
     #   # Exchange 100 USD to CAD:
-    #   bank.exchange(100_00, "USD", "CAD")  # => 80
+    #   bank.exchange_with(c1, "CAD") #=> #<Money @cents=1245150>
     #
+    #   # Exchange 100 CAD to USD:
+    #   bank.exchange_with(c2, "USD") #=> #<Money @cents=803115>
     class VariableExchange < Base
 
+      # Available formats for importing/exporting rates.
       RATE_FORMATS = [:json, :ruby, :yaml]
 
+      # Setup rates hash and mutex for rates locking
+      #
+      # @return [self]
       def setup
         @rates = {}
         @mutex = Mutex.new
+        self
       end
 
-
       # Exchanges the given +Money+ object to a new +Money+ object in
-      # +to_currency+. Returns a new +Money+ object.
+      # +to_currency+.
+      #
+      # @param [Money] from The +Money+ object to exchange.
+      # @param [Currency, String, Symbol] to_currency The currency to exchange
+      #  to.
+      #
+      # @yield [n] Optional block to use when rounding after exchanging one
+      #  currency for another.
+      # @yieldparam [Float] n The resulting float after exchanging one currency
+      #  for another.
+      # @yieldreturn [Integer]
+      #
+      # @return [Money]
+      #
+      # @raise +Money::Bank::UnknownRate+ if the conversion rate is unknown.
       #
-      # Raises <tt>Money::Bank::UnknownRate</tt> if the conversion rate is unknown.
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.add_rate("USD", "CAD", 1.24515)
+      #   bank.add_rate("CAD", "USD", 0.803115)
+      #
+      #   c1 = 100_00.to_money("USD")
+      #   c2 = 100_00.to_money("CAD")
+      #
+      #   # Exchange 100 USD to CAD:
+      #   bank.exchange_with(c1, "CAD") #=> #<Money @cents=1245150>
+      #
+      #   # Exchange 100 CAD to USD:
+      #   bank.exchange_with(c2, "USD") #=> #<Money @cents=803115>
       def exchange_with(from, to_currency, &block)
         return from if same_currency?(from.currency, to_currency)
 
@@ -61,19 +94,54 @@ class Money
         Money.new(ex, _to_currency_)
       end
 
-
-      # Registers a conversion rate. +from+ and +to+ are both currency names or
-      # +Currency+ objects.
+      # Registers a conversion rate and returns it (uses +#set_rate+).
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      # @param [Numeric] rate Rate to use when exchanging currencies.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.add_rate("USD", "CAD", 1.24515)
+      #   bank.add_rate("CAD", "USD", 0.803115)
       def add_rate(from, to, rate)
         set_rate(from, to, rate)
       end
 
-      # Set the rate for the given currencies.
+      # Set the rate for the given currencies. Uses +Mutex+ to synchronize data
+      # access.
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      # @param [Numeric] rate Rate to use when exchanging currencies.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
       def set_rate(from, to, rate)
         @mutex.synchronize { @rates[rate_key_for(from, to)] = rate }
       end
 
-      # Retrieve the rate for the given currencies.
+      # Retrieve the rate for the given currencies. Uses +Mutex+ to synchronize
+      # data access.
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
+      #
+      #   bank.get_rate("USD", "CAD") #=> 1.24515
+      #   bank.get_rate("CAD", "USD") #=> 0.803115
       def get_rate(from, to)
         @mutex.synchronize { @rates[rate_key_for(from, to)] }
       end
@@ -82,7 +150,21 @@ class Money
       # is given will also write the string out to the file specified.
       # Available formats are +:json+, +:ruby+ and +:yaml+.
       #
-      # Raises +Money::Bank::UnknownRateFormat+ if format is unknown.
+      # @param [Symbol] format Request format for the resulting string.
+      # @param [optional, String] file Optional file location to write the
+      #  rates to.
+      #
+      # @return [String]
+      #
+      # @raise +Money::Bank::UnknownRateFormat+ if format is unknown.
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
+      #
+      #   s = bank.export_rates(:json)
+      #   s #=> "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"
       def export_rates(format, file=nil)
         raise Money::Bank::UnknownRateFormat unless
           RATE_FORMATS.include? format
@@ -91,11 +173,11 @@ class Money
         @mutex.synchronize {
           s = case format
               when :json
-                @rates.to_json
+                JSON.dump(@rates)
               when :ruby
                 Marshal.dump(@rates)
               when :yaml
-                @rates.to_yaml
+                YAML.dump(@rates)
               end
 
           unless file.nil?
@@ -108,7 +190,20 @@ class Money
       # Loads rates provided in +s+ given the specified format. Available
       # formats are +:json+, +:ruby+ and +:yaml+.
       #
-      # Raises +Money::Bank::UnknownRateFormat+ if format is unknown.
+      # @param [Symbol] format The format of +s+.
+      # @param [String] s The rates string.
+      #
+      # @return [self]
+      #
+      # @raise +Money::Bank::UnknownRateFormat+ if format is unknown.
+      #
+      # @example
+      #   s = "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.import_rates(:json, s)
+      #
+      #   bank.get_rate("USD", "CAD") #=> 1.24515
+      #   bank.get_rate("CAD", "USD") #=> 0.803115
       def import_rates(format, s)
         raise Money::Bank::UnknownRateFormat unless
           RATE_FORMATS.include? format
@@ -129,11 +224,17 @@ class Money
       private
 
       # Return the rate hashkey for the given currencies.
+      #
+      # @param [Currency, String, Symbol] from The currency to exchange from.
+      # @param [Currency, String, Symbol] to The currency to exchange to.
+      #
+      # @return [String]
+      #
+      # @example
+      #   rate_key_for("USD", "CAD") #=> "USD_TO_CAD"
       def rate_key_for(from, to)
         "#{Currency.wrap(from).iso_code}_TO_#{Currency.wrap(to).iso_code}".upcase
       end
-
     end
-
   end
 end

data/lib/money/core_extensions.rb

@@ -1,11 +1,17 @@
+# Open +Numeric+ to add new method.
 class Numeric
-  # Converts this numeric to a Money object in the default currency. It
-  # multiplies the numeric value by 100 and treats that as cents.
+  # Converts this numeric to a +Money+ object in the default currency.
   #
-  #   100.to_money => #<Money @cents=10000>
-  #   100.37.to_money => #<Money @cents=10037>
+  # @param [optional, Money::Currency, String, Symbol] currency The currency to
+  #  set the resulting +Money+ object to.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   100.to_money                   #=> #<Money @cents=10000>
+  #   100.37.to_money                #=> #<Money @cents=10037>
   #   require 'bigdecimal'
-  #   BigDecimal.new('100').to_money => #<Money @cents=10000>
+  #   BigDecimal.new('100').to_money #=> #<Money @cents=10000>
   def to_money(currency = Money.default_currency)
     currency = Money::Currency.new(currency) unless currency.is_a?(Money::Currency)
     amt = self * currency.subunit_to_unit
@@ -19,22 +25,28 @@ class Numeric
   end
 end
 
+# Open +String+ to add new methods.
 class String
-
-  # Parses the current string and converts it to a Money object.
-  # Excess characters will be discarded.
+  # Parses the current string and converts it to a +Money+ object. Excess
+  # characters will be discarded.
   #
-  #   '100'.to_money       # => #<Money @cents=10000>
-  #   '100.37'.to_money    # => #<Money @cents=10037>
-  #   '100 USD'.to_money   # => #<Money @cents=10000, @currency="USD">
-  #   'USD 100'.to_money   # => #<Money @cents=10000, @currency="USD">
-  #   '$100 USD'.to_money  # => #<Money @cents=10000, @currency="USD">
-  #   'hello 2000 world'.to_money   # => #<Money @cents=200000 @currency="USD")>
+  # @param [optional, Money::Currency, String, Symbol] currency The currency to
+  #  set the resulting +Money+ object to.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   '100'.to_money                #=> #<Money @cents=10000>
+  #   '100.37'.to_money             #=> #<Money @cents=10037>
+  #   '100 USD'.to_money            #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
+  #   'USD 100'.to_money            #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
+  #   '$100 USD'.to_money           #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
+  #   'hello 2000 world'.to_money   #=> #<Money @cents=200000 @currency=#<Money::Currency id: usd>>
   def to_money(currency = nil)
     # Get the currency.
     matches = scan /([A-Z]{2,3})/
     _currency_ = matches[0] ? matches[0][0] : nil
-    
+
     # check that currency passed and embedded currency are the same, or only
     # one or the other is present.
     if currency.nil? and _currency_.nil?
@@ -46,18 +58,28 @@ class String
     elsif currency != _currency_
       raise "mismatching currencies"
     end
-    
+
     cents = calculate_cents(self)
     Money.new(cents, currency)
   end
 
-  # Parses the current string and converts it to a Currency object.
+  # Parses the current string and converts it to a +Currency+ object.
+  #
+  # @return [Money::Currency]
+  #
+  # @example
+  #   "USD".to_currency #=> #<Money::Currency id: usd>
   def to_currency
     Money::Currency.new(self)
   end
 
   private
 
+  # Takes a number string and attempts to massage out the number.
+  #
+  # @param [String] number The string containing a potential number.
+  #
+  # @return [Integer]
   def calculate_cents(number)
     # remove anything that's not a number, potential delimiter, or minus sign
     num = number.gsub(/[^\d|\.|,|\'|\s|\-]/, '').strip
@@ -163,5 +185,4 @@ class String
     # if negative, multiply by -1; otherwise, return positive cents
     negative ? cents * -1 : cents
   end
-
 end

data/lib/money/currency.rb

@@ -6,26 +6,23 @@ class Money
   class Currency
     include Comparable
 
+    # Thrown when an unknown currency is requested.
     class UnknownCurrency < StandardError; end
 
     # List of attributes applicable to a currency object.
-    #  * priority: a numerical value you can use to sort/group the currency list
-    #  * iso_code: the international 3-letter code as defined by the ISO 4217 standard
-    #  * name: the currency name
-    #  * symbol: the currency symbol (UTF-8 encoded)
-    #  * subunit: the name of the fractional monetary unit
-    #  * subunit_to_unit: the proportion between the unit and the subunit
     ATTRIBUTES = [ :priority, :iso_code, :name, :symbol, :subunit, :subunit_to_unit, :separator, :delimiter ]
 
+    # List of known currencies.
+    #
+    # == monetary unit
+    # The standard unit of value of a currency, as the dollar in the United States or the peso in Mexico.
+    # http://www.answers.com/topic/monetary-unit
+    # == fractional monetary unit, subunit
+    # A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit
+    # http://www.answers.com/topic/fractional-monetary-unit-subunit
+    #
+    # See http://en.wikipedia.org/wiki/List_of_circulating_currencies
     TABLE = {
-      # monetary unit
-      #   The standard unit of value of a currency, as the dollar in the United States or the peso in Mexico.
-      #   http://www.answers.com/topic/monetary-unit
-      # fractional monetary unit, subunit
-      #   A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit
-      #   http://www.answers.com/topic/fractional-monetary-unit-subunit
-      #
-      # See http://en.wikipedia.org/wiki/List_of_circulating_currencies
       :aed => { :priority => 100, :iso_code => "AED", :name => "United Arab Emirates Dirham",               :symbol => "د.إ",           :subunit => "Fils",          :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :afn => { :priority => 100, :iso_code => "AFN", :name => "Afghan Afghani",                            :symbol => "؋",             :subunit => "Pul",           :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :all => { :priority => 100, :iso_code => "ALL", :name => "Albanian Lek",                              :symbol => "L",             :subunit => "Qintar",        :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
@@ -76,7 +73,7 @@ class Money
       :fkp => { :priority => 100, :iso_code => "FKP", :name => "Falkland Pound",                            :symbol => "£",             :subunit => "Penny",         :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :gbp => { :priority =>   3, :iso_code => "GBP", :name => "British Pound",                             :symbol => "£",             :subunit => "Penny",         :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :gel => { :priority => 100, :iso_code => "GEL", :name => "Georgian Lari",                             :symbol => "ლ",             :subunit => "Tetri",         :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
-      :ghc => { :priority => 100, :iso_code => "GHC", :name => "Ghanaian Cedi",                             :symbol => "₵",             :subunit => "Pesewa",        :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
+      :ghs => { :priority => 100, :iso_code => "GHS", :name => "Ghanaian Cedi",                             :symbol => "₵",             :subunit => "Pesewa",        :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :gip => { :priority => 100, :iso_code => "GIP", :name => "Gibraltar Pound",                           :symbol => "£",             :subunit => "Penny",         :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :gmd => { :priority => 100, :iso_code => "GMD", :name => "Gambian Dalasi",                            :symbol => "D",             :subunit => "Butut",         :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
       :gnf => { :priority => 100, :iso_code => "GNF", :name => "Guinean Franc",                             :symbol => "Fr",            :subunit => "Centime",       :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
@@ -192,10 +189,66 @@ class Money
 
       # aliases for BC with documentation before Currency
       :yen => { :priority => 100, :iso_code => "JPY", :name => "Japanese Yen",                              :symbol => "¥",             :subunit => "Sen",           :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
+
+      # kept for backwards compatibility, real entry is :ghs
+      :ghc => { :priority => 100, :iso_code => "GHS", :name => "Ghanaian Cedi",                             :symbol => "₵",             :subunit => "Pesewa",        :subunit_to_unit => 100, :separator => ".", :delimiter => ","   },
     }
 
-    attr_reader :id, *ATTRIBUTES
+    # The symbol used to identify the currency, usually the lowercase
+    # +iso_code+ attribute.
+    #
+    # @return [Symbol]
+    attr_reader :id
+
+    # A numerical value you can use to sort/group the currency list.
+    #
+    # @return [Integer]
+    attr_reader :priority
+
+    # The international 3-letter code as defined by the ISO 4217 standard.
+    #
+    # @return [String]
+    attr_reader :iso_code
+
+    # The currency name.
+    #
+    # @return [String]
+    attr_reader :name
+
+    # The currency symbol (UTF-8 encoded).
+    #
+    # @return [String]
+    attr_reader :symbol
+
+    # The name of the fractional monetary unit.
+    #
+    # @return [String]
+    attr_reader :subunit
+
+    # The proportion between the unit and the subunit
+    #
+    # @return [Integer]
+    attr_reader :subunit_to_unit
+
+    # The character used to separate the whole unit from the subunit.
+    #
+    # @return [String]
+    attr_reader :separator
+
+    # The character used to separate thousands grouping of the whole unit.
+    #
+    # @return [String]
+    attr_reader :delimiter
 
+    # Create a new +Currency+ object.
+    #
+    # @param [String, Symbol, #to_s] id Used to look into +TABLE+ and retrieve
+    #  the applicable attributes.
+    #
+    # @return [Money::Currency]
+    #
+    # @example
+    #   Money::Currency.new(:usd) #=> #<Money::Currency id: usd ...>
     def initialize(id)
       @id  = id.to_s.downcase.to_sym
       data = TABLE[@id] || raise(UnknownCurrency, "Unknown currency `#{id}'")
@@ -204,74 +257,112 @@ class Money
       end
     end
 
-    # Compares <tt>self</tt> with <tt>other_currency</tt>
-    # against the value of <tt>priority</tt> attribute.
+    # Compares +self+ with +other_currency+ against the value of +priority+
+    # attribute.
+    #
+    # @param [Money::Currency] other_currency The currency to compare to.
+    #
+    # @return [-1,0,1] -1 if less than, 0 is equal to, 1 if greater than
+    #
+    # @example
+    #   c1 = Money::Currency.new(:usd)
+    #   c2 = Money::Currency.new(:jpy)
+    #   c1 <=> c2 #=> 1
+    #   c2 <=> c1 #=> -1
+    #   c1 <=> c1 #=> 0
     def <=>(other_currency)
       self.priority <=> other_currency.priority
     end
 
-    # Returns <tt>true</tt> if <tt>self.iso_code</tt>
-    # is equal to <tt>other_currency.iso_code</tt>
+    # Compares +self+ with +other_currency+ and returns +true+ if the are the
+    # same or if their +id+ attributes match.
+    #
+    # @param [Money::Currency] other_currency The currency to compare to.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   c1 = Money::Currency.new(:usd)
+    #   c2 = Money::Currency.new(:jpy)
+    #   c1 == c1 #=> true
+    #   c1 == c2 #=> false
     def ==(other_currency)
       self.equal?(other_currency) ||
       self.id == other_currency.id
     end
 
-    # synonymous with #==
+    # Compares +self+ with +other_currency+ and returns +true+ if the are the
+    # same or if their +id+ attributes match.
+    #
+    # @param [Money::Currency] other_currency The currency to compare to.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   c1 = Money::Currency.new(:usd)
+    #   c2 = Money::Currency.new(:jpy)
+    #   c1.eql? c1 #=> true
+    #   c1.eql? c2 #=> false
     def eql?(other_currency)
       self == other_currency
     end
 
-    # Returns a Fixnum hash value based on the <tt>id</tt> attribute
-    # in order to use functions like & (intersection), group_by, etc.
+    # Returns a Fixnum hash value based on the +id+ attribute in order to use
+    # functions like & (intersection), group_by, etc.
     #
-    #   [Currency.new(:usd), Currency.new(:eur)] & [Currency.new(:usd)]
-    #   # => [Currency.new(:usd)]
+    # @return [Fixnum]
     #
+    # @example
+    #   Money::Currency.new(:usd).hash #=> 428936
     def hash
       id.hash
     end
 
-    # Returns a string representation
-    # corresponding to the upcase <tt>id</tt> attribute.
-    #
-    #   Currency.new(:usd).to_s
-    #   # => "USD"
-    #   Currency.new(:eur).to_s
-    #   # => "EUR"
+    # Returns a string representation corresponding to the upcase +id+
+    # attribute.
     #
     # -–
-    # DEV: id.to_s.upcase corresponds to iso_code
-    # but don't use ISO_CODE for consistency.
+    # DEV: id.to_s.upcase corresponds to iso_code but don't use ISO_CODE for consistency.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Money::Currency.new(:usd).to_s #=> "USD"
+    #   Money::Currency.new(:eur).to_s #=> "EUR"
     def to_s
       id.to_s.upcase
     end
 
     # Returns a human readable representation.
     #
-    #   #<Currency id:usd>
+    # @return [String]
     #
+    # @example
+    #   Money::Currency.new(:usd) #=> #<Currency id: usd ...>
     def inspect
       "#<#{self.class.name} id: #{id} #{ATTRIBUTES.map { |a| "#{a}: #{send(a)}" }.join(", ")}>"
     end
 
-
+    # Catches deprecated uses of currency.
     def method_missing(method, *args, &block)
-      Money.deprecate "`currency' is now a Currency instance. Call `currency.to_s.#{method}' instead."
+      Money.deprecate "`currency` is now a `Currency` instance. Call `currency.to_s.#{method}' instead."
       iso_code.send(method, *args, &block)
     end
 
+    # Class Methods
     class << self
 
-      # Lookup a Currency with given <tt>id</tt>
-      # an returns a <tt>Currency</tt> instance on success,
-      # <tt>nil</tt> otherwise.
+      # Lookup a currency with given +id+ an returns a +Currency+ instance on
+      # success, +nil+ otherwise.
+      #
+      # @param [String, Symbol, #to_s] id Used to look into +TABLE+ and
+      # retrieve the applicable attributes.
       #
-      #   Currency.find(:eur)
-      #   # => <#Currency id: eur ...>
-      #   Currency.find(:foo)
-      #   # => nil
+      # @return [Money::Currency]
       #
+      # @example
+      #   Money::Currency.find(:eur) #=> #<Money::Currency id: eur ...>
+      #   Money::Currency.find(:foo) #=> nil
       def find(id)
         id = id.to_s.downcase.to_sym
         if data = self::TABLE[id]
@@ -279,15 +370,19 @@ class Money
         end
       end
 
-      # Wraps the object in a Currency unless it's a Currency.
+      # Wraps the object in a +Currency+ unless it's already a +Currency+
+      # object.
+      #
+      # @param [Object] object The object to attempt and wrap as a +Currency+
+      # object.
       #
-      #   Currency.wrap(nil)
-      #   # => nil
-      #   Currency.wrap(Currency.new(:usd))
-      #   # => <#Currency id: usd ...>
-      #   Currency.wrap("usd")
-      #   # => <#Currency id: usd ...>
+      # @return [Money::Currency]
       #
+      # @example
+      #   c1 = Money::Currency.new(:usd)
+      #   Money::Currency.wrap(nil)   #=> nil
+      #   Money::Currency.wrap(c1)    #=> #<Money::Currency id: usd ...>
+      #   Money::Currency.wrap("usd") #=> #<Money::Currency id: usd ...>
       def wrap(object)
         if object.nil?
           nil
@@ -297,8 +392,6 @@ class Money
           Currency.new(object)
         end
       end
-
     end
-
   end
 end