Merge pull request #1153 from sunny/deprecate-calling-dollars-on-non-dollars

Deprecate `Money#dollars` and `Money.from_dollars`

Author: yukideluxe

CHANGELOG.md

@@ -37,6 +37,8 @@
     ```
 - Add `Money#to_nearest_cash_value` to return a rounded Money instance to the smallest denomination
 - Deprecate `Money#round_to_nearest_cash_value` in favor of calling `to_nearest_cash_value.fractional`
+- Deprecate `Money#dollars` in favor of `Money#amount`.
+- Deprecate `Money.from_dollars` in favor of `Money.from_amount`.
 - Add `Money::Currency#cents_based?` to check if currency is cents-based
 - Add ability to nest `Money.with_rounding_mode` blocks
 - Allow `nil` to be used as a default_currency

lib/money/money.rb

@@ -345,9 +345,18 @@ def self.from_amount(amount, currency = default_currency, options = {})
     new(value, currency, options)
   end
 
+  # DEPRECATED.
+  #
+  # @see Money.from_amount
+  def self.from_dollars(amount, currency = default_currency, options = {})
+    warn "[DEPRECATION] `Money.from_dollars` is deprecated in favor of " \
+         "`Money.from_amount`."
+
+    from_amount(amount, currency, options)
+  end
+
   class << self
     alias_method :from_cents, :new
-    alias_method :from_dollars, :from_amount
   end
 
   # Creates a new Money object of value given in the
@@ -388,35 +397,25 @@ def initialize(obj, currency = nil, options = {})
     raise Currency::NoCurrency, 'must provide a currency' if @currency.nil?
   end
 
-  # Assuming using a currency using dollars:
-  # Returns the value of the money in dollars,
-  # instead of in the fractional unit cents.
-  #
-  # Synonym of #amount
-  #
-  # @return [BigDecimal]
-  #
-  # @example
-  #   Money.new(1_00, "USD").dollars   # => BigDecimal("1.00")
+  # DEPRECATED.
   #
   # @see #amount
-  # @see #to_d
-  # @see #cents
-  #
   def dollars
+    warn "[DEPRECATION] `Money#dollars` is deprecated in favor of " \
+         "`Money#amount`."
+
     amount
   end
 
-  # Returns the numerical value of the money
+  # Returns the numerical value of the money.
   #
   # @return [BigDecimal]
   #
   # @example
-  #   Money.new(1_00, "USD").amount    # => BigDecimal("1.00")
+  #   Money.new(1_00, "USD").amount # => BigDecimal("1.00")
   #
   # @see #to_d
   # @see #fractional
-  #
   def amount
     to_d
   end
@@ -619,9 +618,7 @@ def allocate(parts)
   # @example
   #   Money.new(10.1, 'USD').round #=> Money.new(10, 'USD')
   #
-  # @see
-  #   Money.default_infinite_precision
-  #
+  # @see Money.default_infinite_precision
   def round(rounding_mode = self.class.rounding_mode, rounding_precision = 0)
     rounded_amount = as_d(@fractional).round(rounding_precision, rounding_mode)
     dup_with(fractional: rounded_amount)

sig/lib/money/money.rbs

@@ -308,9 +308,12 @@ class Money
   # @see #initialize
   def self.from_amount: (Numeric amount, ?(Money::Currency | string | Symbol) currency, ?::Hash[untyped, untyped] options) -> Money
 
-  alias self.from_cents self.new
+  # DEPRECATED.
+  #
+  # @see Money.from_amount
+  def self.from_amount: (Numeric amount, ?(Money::Currency | string | Symbol) currency, ?::Hash[untyped, untyped] options) -> Money
 
-  alias self.from_dollars self.from_amount
+  alias self.from_cents self.new
 
   # Creates a new Money object of value given in the
   # +fractional unit+ of the given +currency+.
@@ -335,33 +338,20 @@ class Money
   #
   def initialize: (Object obj, ?(Money::Currency | string | Symbol) currency, ?::Hash[untyped, untyped] options) -> Money
 
-  # Assuming using a currency using dollars:
-  # Returns the value of the money in dollars,
-  # instead of in the fractional unit cents.
-  #
-  # Synonym of #amount
-  #
-  # @return [BigDecimal]
-  #
-  # @example
-  #   Money.new(1_00, "USD").dollars   # => BigDecimal("1.00")
+  # DEPRECATED.
   #
   # @see #amount
-  # @see #to_d
-  # @see #cents
-  #
   def dollars: () -> BigDecimal
 
-  # Returns the numerical value of the money
+  # Returns the numerical value of the money.
   #
   # @return [BigDecimal]
   #
   # @example
-  #   Money.new(1_00, "USD").amount    # => BigDecimal("1.00")
+  #   Money.new(1_00, "USD").amount # => BigDecimal("1.00")
   #
   # @see #to_d
   # @see #fractional
-  #
   def amount: () -> BigDecimal
 
   # Returns a Integer hash value based on the +fractional+ and +currency+ attributes
@@ -516,9 +506,7 @@ class Money
   # @example
   #   Money.new(10.1, 'USD').round #=> Money.new(10, 'USD')
   #
-  # @see
-  #   Money.default_infinite_precision
-  #
+  # @see Money.default_infinite_precision
   def round: (?untyped rounding_mode, ?::Integer rounding_precision) -> Money
 
   # Creates a formatted price string according to several rules.

spec/money_spec.rb

@@ -135,8 +135,10 @@
     context 'initializing with .from_dollars' do
       subject(:money) { Money.from_dollars(initializing_value) }
 
-      it 'works just as with .from_amount' do
-        expect(money.dollars).to eq initializing_value
+      it "is a deprecated synonym of .from_amount" do
+        allow(Money).to receive(:warn)
+        expect(money.amount).to eq initializing_value
+        expect(Money).to have_received(:warn).with(/DEPRECATION/)
       end
     end
   end
@@ -587,7 +589,7 @@
   end
 
   describe "#amount" do
-    it "returns the amount of cents as dollars" do
+    it "returns the amount of cents as the full unit" do
       expect(Money.new(1_00).amount).to eq 1
     end
 
@@ -608,15 +610,12 @@
   end
 
   describe "#dollars" do
-    it "is synonym of #amount" do
-      m = Money.new(0)
+    it "is a deprecated synonym of #amount" do
+      money = Money.new(1_23)
 
-      # Make a small expectation
-      def m.amount
-        5
-      end
-
-      expect(m.dollars).to eq 5
+      allow(money).to receive(:warn)
+      expect(money.dollars).to eq(1.23)
+      expect(money).to have_received(:warn).with(/DEPRECATION/)
     end
   end
 
@@ -642,14 +641,20 @@ def m.amount
   end
 
   describe "#symbol" do
-    it "works as documented" do
-      currency = Money::Currency.new("EUR")
-      expect(currency).to receive(:symbol).and_return("€")
-      expect(Money.new(0, currency).symbol).to eq "€"
+    it "returns the currency’s symbol" do
+      expect(Money.new(0, "EUR").symbol).to eq("€")
+    end
 
-      currency = Money::Currency.new("EUR")
-      expect(currency).to receive(:symbol).and_return(nil)
-      expect(Money.new(0, currency).symbol).to eq "¤"
+    context "when the currency has no symbol" do
+      let(:currency) { Money::Currency.new("EUR") }
+
+      before do
+        expect(currency).to receive(:symbol).and_return(nil)
+      end
+
+      it "returns a generic currency symbol" do
+        expect(Money.new(0, currency).symbol).to eq "¤"
+      end
     end
   end