Deprecate Money#dollars when the currency is not USD

Author: sunny

CHANGELOG.md

@@ -23,6 +23,7 @@
 - Add Caribbean Guilder (XCG) as replacement for Netherlands Antillean Gulden (ANG)
 - 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` when the currency is not USD, prefer calling `#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

@@ -365,34 +365,37 @@ def initialize(obj, currency = nil, options = {})
   end
 
   # Assuming using a currency using dollars:
-  # Returns the value of the money in dollars,
-  # instead of in the fractional unit cents.
+  # 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")
+  #   Money.new(1_00, "USD").dollars # => BigDecimal("1.00")
   #
   # @see #amount
   # @see #to_d
   # @see #cents
-  #
   def dollars
+    unless currency == "USD"
+      warn "[DEPRECATION] `#dollars` was called on an instance of Money in " \
+           "#{currency}. Prefer calling `#amount` instead."
+    end
+
     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
@@ -595,9 +598,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

@@ -318,32 +318,30 @@ 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.
+  # 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")
+  #   Money.new(1_00, "USD").dollars # => BigDecimal("1.00")
   #
   # @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
@@ -498,9 +496,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

@@ -614,15 +614,18 @@ def expectation.fractional
   end
 
   describe "#dollars" do
-    it "is synonym of #amount" do
-      m = Money.new(0)
+    it "is a synonym of #amount" do
+      expect(Money.new(1_23, "USD").dollars).to eq(1.23)
+    end
 
-      # Make a small expectation
-      def m.amount
-        5
-      end
+    context "when using another currency" do
+      it "warns" do
+        amount = Money.new(1_23, "EUR")
 
-      expect(m.dollars).to eq 5
+        allow(amount).to receive(:warn)
+        expect(amount.dollars).to eq(1.23)
+        expect(amount).to have_received(:warn).with(/DEPRECATION/)
+      end
     end
   end
 
@@ -648,14 +651,16 @@ 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
+      it "returns a generic currency symbol" do
+        currency = Money::Currency.new("EUR")
+        expect(currency).to receive(:symbol).and_return(nil)
+        expect(Money.new(0, currency).symbol).to eq "¤"
+      end
     end
   end