Add caveat to number_to_currency docs [ci skip]

I've worked on a few applications that have gone through the
internationalization process and had issues because they were using
`number_to_currency`. The minute a user is allowed to change their
locale, they can change the price displayed on a page from 10 US dollars
to 10 Mexican Pesos, which is far from the same amount of money.

Unlike other helpers that rely on i18n, `number_to_currency` does not
produce equivalent results when the locale is changed.

As I've explained this to a few groups of developers now, I thought it
might make for a good caveat in the docs.

1 files changed, 8 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/number_helper.rb b/activesupport/lib/active_support/number_helper.rb
index 248521e677..92a453be48 100644
--- a/activesupport/lib/active_support/number_helper.rb
+++ b/activesupport/lib/active_support/number_helper.rb
@@ -47,6 +47,14 @@ module ActiveSupport
     # Formats a +number+ into a currency string (e.g., $13.65). You
     # can customize the format in the +options+ hash.
     #
+    # The currency unit and number formatting of the current locale will be used
+    # unless otherwise specified in the provided options. No currency conversion
+    # is performed. If the user is given a way to change their locale, they will
+    # also be able to change the relative value of the currency displayed with
+    # this helper. If your application will ever support multiple locales, you
+    # may want to specify a constant <tt>:locale</tt> option or consider
+    # using a library capable of currency conversion.
+    #
     # ==== Options
     #
     # * <tt>:locale</tt> - Sets the locale to be used for formatting