money_attribute 1.1.0 → 1.2.1

data/lib/money_attribute/configuration.rb

@@ -1,27 +1,55 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  class Configuration
-    attr_accessor :added_currencies, :default_currency
+  # @private
+  CONFIG_MUTEX = Mutex.new
 
-    def initialize
-      @added_currencies = []
-      @default_currency = 'USD'
+  class << self
+    # Returns the lazily initialized gem configuration.
+    #
+    # @return [Config]
+    def config
+      CONFIG_MUTEX.synchronize { @config ||= Config.new }
     end
-  end
 
-  cfg = Configuration.new
-  cached_default = nil
+    # Yields the current configuration object for mutation.
+    #
+    # @yield [config] the current configuration
+    # @return [void]
+    def configure = yield config
+
+    # Returns the current request or default currency as a resolved currency.
+    # Memoized per-thread — within a request, Current.currency is stable.
+    #
+    # @return [Mint::Currency]
+    def default_currency
+      code = MoneyAttribute::Current.currency.presence || config.default_currency
 
-  define_singleton_method(:config) { cfg }
+      last_code, last_currency = Thread.current[:money_attribute_default_currency]
+      return last_currency if last_code == code
 
-  define_singleton_method(:configure) do |&block|
-    block&.call(cfg)
-    cached_default = nil
-    cfg
+      currency = Money::Currency.resolve!(code)
+      Thread.current[:money_attribute_default_currency] = [code, currency]
+      currency
+    end
   end
 
-  define_singleton_method(:default_currency) do
-    cached_default ||= ::Mint::Currency.resolve!(cfg.default_currency)
+  # Gem configuration holding the default currency and registered custom currencies.
+  #
+  #   MoneyAttribute.configure do |config|
+  #     config.default_currency = 'BRL'
+  #   end
+  class Config
+    # @return [String] ISO 4217 currency code used when no per-request or per-row currency is set.
+    attr_accessor :default_currency
+
+    # @return [Array<Hash>] custom currencies registered via +register_custom_currencies!+.
+    attr_accessor :added_currencies
+
+    # Initializes the default gem configuration values.
+    def initialize
+      @default_currency = 'USD'
+      @added_currencies = []
+    end
   end
 end

data/lib/money_attribute/converter.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Converts raw attribute input into +Mint::Money+ values.
+  #
+  # Used in two roles: as the +:converter+ option of +composed_of+ (composite
+  # attributes) and as the normalizer block for +money_amount+ (single-column
+  # attributes). Accepts +Mint::Money+, numeric, string, and +nil+ input.
   class Converter
-    def initialize(currency = MoneyAttribute.default_currency)
-      @default_currency = currency
+    DEFAULT = new.freeze
+
+    # Initializes a converter with an optional fixed currency.
+    #
+    # @param currency [String, Symbol, Mint::Currency, nil] the currency to use
+    #   for parsed values; falls back to {MoneyAttribute.default_currency} when nil
+    # @return [Converter]
+    def initialize(currency = nil)
+      @static_currency = currency
+    end
+
+    # Returns the shared default converter instance.
+    #
+    # @return [Converter] the frozen, process-wide converter
+    def self.default
+      DEFAULT
     end
 
+    # Converts raw input into a +Mint::Money+ value.
+    #
+    # @param amount [Mint::Money, Numeric, String, nil] the input value
+    # @return [Mint::Money, nil] +Mint::Money+ for numeric and string input,
+    #   the input itself for +Mint::Money+ and +nil+
+    # @raise [ArgumentError] for unsupported input types
     def parse(amount)
+      currency = @static_currency || MoneyAttribute.default_currency
       case amount
       when Money, NilClass      then amount
-      when Numeric              then Money.from(amount, @default_currency)
-      when String               then Money.parse(amount, @default_currency)
+      when Numeric              then Money.from(amount, currency)
+      when String               then Money.parse(amount, currency)
       else raise ArgumentError, "Cannot convert #{amount.inspect} (#{amount.class}) to Money"
       end
     end

data/lib/money_attribute/core_ext/numeric.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Convenience method for converting numeric values to +Mint::Money+.
+#
+# @api private
+class Numeric
+  remove_method :to_money if method_defined?(:to_money)
+
+  # Converts the numeric value to a +Mint::Money+ value.
+  #
+  # @param currency [String, Symbol, Mint::Currency, nil] the currency to use;
+  #   falls back to {MoneyAttribute.default_currency}
+  # @return [Mint::Money]
+  # @example
+  #   42.5.to_money('USD') # => Mint::Money(42.5, 'USD')
+  def to_money(currency = MoneyAttribute.default_currency) = Money.from(self, currency)
+end

data/lib/money_attribute/core_ext/string.rb

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
-# :nodoc:
+# Convenience method for parsing +Mint::Money+ from strings.
+#
+# @api private
 class String
   remove_method :to_money if method_defined?(:to_money)
 
+  # Parses the string into a +Mint::Money+ value.
+  #
+  # @param currency [String, Symbol, Mint::Currency, nil] the currency to use;
+  #   falls back to {MoneyAttribute.default_currency}
+  # @return [Mint::Money]
+  # @raise [ArgumentError] if the string cannot be parsed
+  # @example
+  #   '12.34'.to_money('USD') # => Mint::Money(12.34, 'USD')
   def to_money(currency = MoneyAttribute.default_currency) = Money.parse(self, currency)
 end

data/lib/money_attribute/current.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module MoneyAttribute
+  # Per-request currency container. Set MoneyAttribute::Current.currency in your
+  # controller (or a before_action) to override the configured default for that request.
+  # Automatically reset after each request by MoneyAttribute::Middleware.
+  class Current < ::ActiveSupport::CurrentAttributes
+    # @return [String, nil] per-request ISO 4217 currency code override.
+    attribute :currency
+  end
+end

data/lib/money_attribute/form_builder_extension.rb

@@ -1,8 +1,39 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Form builder methods for money attributes.
+  #
+  # Included into +ActionView::Helpers::FormBuilder+ by the railtie,
+  # providing two helper methods that mirror Rails' +text_field+ and
+  # +number_field+ but work with +Mint::Money+ attribute values.
+  #
+  # Both helpers render unbound <tt>&lt;input&gt;</tt> tags (not scoped to
+  # the form builder's object name), so the submitted value is accessible
+  # via +params+ directly rather than through +params[object_name]+.
+  #
+  # @example In a view
+  #   <%= form_with model: @product do |f| %>
+  #     <%= f.money_field :price %>
+  #     <%= f.money_amount_field :discount %>
+  #   <% end %>
   module FormBuilderExtension
+    # Renders a text input for a composed (amount + currency) money attribute.
+    #
+    # Displays the formatted money string (e.g. +"R$ 1.234,56"+) via
+    # {Mint::Money#to_fs}. The raw value is submitted as a string; the
+    # application should parse it on the receiving end, typically using
+    # {MoneyAttribute::Converter#parse}.
+    #
+    # @param method [Symbol] the money attribute accessor name
+    # @param options [Hash] HTML attributes passed through to the input tag
+    # @return [String] an HTML <tt>&lt;input type="text"&gt;</tt> tag
+    #
+    # @example
+    #   f.money_field :price
+    #   # => <input type="text" id="product_price" name="product_price" value="R$ 1.234,56">
+    #
+    # @example With CSS class
+    #   f.money_field :price, class: "form-control"
     def money_field(method, options = {})
       money = object.public_send(method)
       value = money&.to_fs
@@ -11,6 +42,22 @@ module MoneyAttribute
                                { id: field_id(method) }.merge(options))
     end
 
+    # Renders a number input for a single-column (fixed-currency) money attribute.
+    #
+    # Displays the raw decimal value (e.g. +"1234.56"+) via
+    # {Mint::Money#to_d}. This is suitable for attributes backed by a single
+    # column where the currency is fixed per application config.
+    #
+    # @param method [Symbol] the money attribute accessor name
+    # @param options [Hash] HTML attributes passed through to the input tag
+    # @return [String] an HTML <tt>&lt;input type="number"&gt;</tt> tag
+    #
+    # @example
+    #   f.money_amount_field :discount
+    #   # => <input type="number" id="product_discount" name="product_discount" value="1234.56">
+    #
+    # @example With step and min
+    #   f.money_amount_field :discount, step: 0.01, min: 0
     def money_amount_field(method, options = {})
       money_from_column = object.public_send(method)
       value = money_from_column&.to_d

data/lib/money_attribute/macro.rb

@@ -1,101 +1,135 @@
 # frozen_string_literal: true
 
 module MoneyAttribute
-  # :nodoc:
+  # Declares composite money attributes on Active Record models.
+  #
+  # Provides the +money_attribute+ class method which wires a two-column
+  # (amount + currency) backing store to a +Mint::Money+ value object via
+  # +composed_of+.
+  #
+  # @example
+  #   class Product < ApplicationRecord
+  #     money_attribute :price
+  #   end
   module Macro
     extend ActiveSupport::Concern
 
-    # :nodoc:
+    # Class methods backing the +money_attribute+ macro.
+    #
+    # @api private
     module CompositeClassMethods
-      def resolve_composite_mapping(name)
-        columns = attribute_names
-        if columns.include?("#{name}_currency")
-          return { amount: name, currency: :"#{name}_currency" } if columns.include?(name)
-
-          nil
-        elsif name == 'amount' && columns.include?('currency')
-          { amount: name, currency: :currency }
-        end
+      include ColumnTypeValidations
+
+      # Normalizes the requested mapping by applying conventions and overrides.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping_override [Hash] the user-supplied +mapping:+ option
+      # @return [Hash{Symbol => String}] resolved +:amount+ and +:currency+ column names
+      # @raise [ArgumentError] if the resolved columns do not exist on the model
+      # @api private
+      def resolve_mapping(name, mapping_override)
+        override = mapping_override.compact
+        override.slice!(:amount, :currency)
+        override.transform_values!(&:to_s)
+
+        mapping = default_mapping(name).merge(override)
+
+        assert_columns_exist!(name, mapping)
+        mapping
       end
 
-      def resolve_composite_for(name, mapping:)
-        composite = { amount: "#{name}_amount", currency: "#{name}_currency" }
+      # Returns the default amount/currency mapping for the attribute name.
+      #
+      # Resolution order: +name_currency+ + +name+ columns, +amount+ + +currency+
+      # for +:amount+, then the +name_amount+ + +name_currency+ convention.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @return [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @api private
+      def default_mapping(name)
+        name = name.to_s
+        names = column_names
 
-        composite[:amount]   = mapping[:amount].to_s if mapping&.key?(:amount)
-        composite[:currency] = mapping[:currency].to_s if mapping&.key?(:currency)
+        if names.include?("#{name}_currency") && names.include?(name)
+          { amount: name, currency: "#{name}_currency" }
+        elsif name == 'amount' && names.include?('currency')
+          { amount: name, currency: 'currency' }
+        else
+          { amount: "#{name}_amount", currency: "#{name}_currency" }
+        end
+      end
 
-        assert_columns_exist!(name, composite)
-        composite
+      # Registers the composite money attribute spec for the model.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @return [AttributeSpec] the registered spec
+      # @raise [ArgumentError] if either column has an unsupported type
+      # @api private
+      def register_composite_spec(name, mapping)
+        amount_column = column_for_attribute(mapping[:amount])
+        currency_column = column_for_attribute(mapping[:currency])
+
+        assert_valid_amount_column!(name, mapping[:amount], amount_column)
+        assert_valid_currency_column!(name, mapping[:currency], currency_column)
+
+        register_money_attribute_spec(
+          name,
+          kind: :composite,
+          amount_column: mapping[:amount],
+          currency_column: mapping[:currency],
+          amount_type: %i[integer bigint].include?(amount_column.type) ? :integer : :decimal
+        )
       end
 
-      def assert_columns_exist!(name, composite)
-        missing = composite.values - attribute_names
+      # Raises when the resolved columns are not present on the model.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash{Symbol => String}] +:amount+ and +:currency+ column names
+      # @return [void]
+      # @raise [ArgumentError] listing expected vs found columns
+      # @api private
+      def assert_columns_exist!(name, mapping)
+        missing = mapping.values - column_names
         return if missing.empty?
 
         raise ArgumentError,
               "Could not find columns for :#{name} money attribute. " \
-              "Expected: #{composite.values.join(', ')}, " \
+              "Expected: #{mapping.values.join(', ')}, " \
               "Found: #{attribute_names.join(', ')}"
       end
+    end
 
-      def amount_extractor_for(column_name) = integer_column?(column_name) ? :subunits : :to_d
-
-      def money_constructor_for(amount_column)
-        default = MoneyAttribute.default_currency
-        if integer_column?(amount_column)
-          build_money_constructor(:from_subunits, default)
-        else
-          build_money_constructor(:from, default)
-        end
-      end
-
-      def build_money_constructor(method, default)
-        lambda do |amount, currency|
-          next nil if amount.nil?
-
-          resolved = Mint::Currency.resolve(currency.presence || default) || 'XXX'
-          Mint::Money.public_send(method, amount, resolved)
-        end
-      end
-
-      def integer_column?(column_name)
-        col = columns.find { |c| c.name == column_name }
-        %i[integer bigint].include?(col&.type)
-      end
-
-      def define_composite_money_attribute(name, mapping, currency)
-        aggregated = resolve_composite_for(name, mapping:)
-
-        composed_of(name.to_sym, {
+    class_methods do
+      # Declares a composite money attribute on the model.
+      #
+      # Stores the attribute across two columns (amount + currency). The amount
+      # column type determines the storage unit: integer/bigint stores subunits,
+      # decimal stores the unit value. Currency is resolved per row.
+      #
+      # @param name [Symbol, String] the money attribute accessor name
+      # @param mapping [Hash] custom column mapping (+:amount+, +:currency+)
+      # @return [void]
+      #
+      # @example
+      #   class Product < ApplicationRecord
+      #     money_attribute :price
+      #     money_attribute :price, mapping: { amount: :base_price, currency: :base_currency }
+      #   end
+      def money_attribute(name, mapping: {})
+        mapping = resolve_mapping(name, mapping)
+        spec = register_composite_spec(name, mapping)
+
+        composed_of(name, {
                       allow_nil: true,
                       class_name: 'Mint::Money',
-                      constructor: money_constructor_for(aggregated[:amount]),
-                      converter: Converter.new(currency),
-                      mapping: {
-                        aggregated[:amount] => amount_extractor_for(aggregated[:amount]),
-                        aggregated[:currency] => :currency_code
-                      }
+                      constructor: spec.constructor,
+                      converter: Converter.default,
+                      mapping: spec.composed_of_mapping
                     })
       end
     end
 
-    class_methods do
-      def money_attribute(name, currency: MoneyAttribute.default_currency, mapping: nil)
-        name = name.to_s
-        currency = ::Mint::Currency.resolve!(currency)
-        resolved_mapping = mapping || resolve_composite_mapping(name)
-
-        if resolved_mapping.nil? && attribute_names.include?(name)
-          raise ArgumentError,
-                "Column '#{name}' exists but no '#{name}_currency' column was found. " \
-                'For single-column fixed-currency attributes, use `money_amount` ' \
-                'instead of `money_attribute`.'
-        end
-
-        define_composite_money_attribute(name, resolved_mapping || {}, currency)
-      end
-    end
-
     included do
       extend CompositeClassMethods
     end

data/lib/money_attribute/migration_extensions/helper.rb

@@ -2,7 +2,19 @@
 
 module MoneyAttribute
   module MigrationExtensions
-    # :nodoc:
+    # Shared argument-parsing logic for migration helpers.
+    #
+    # Resolves accessor names, column overrides, and amount type configuration
+    # into concrete column definitions. Included by both {SchemaStatements} and
+    # {TableDefinition}.
+    #
+    # @!attribute [rw] AMOUNT_CONFIG
+    #   @return [Hash{Symbol => Hash}] mapping of symbolic type names to
+    #     column type/hash pairs
+    # @!attribute [rw] CURRENCY_MIN_LIMIT
+    #   @return [Integer] minimum allowed currency column string limit (8)
+    # @!attribute [rw] CURRENCY_DEFAULT_LIMIT
+    #   @return [Integer] default currency column string limit (20)
     module Helper
       AMOUNT_CONFIG = {
         crypto_decimal: { type: :decimal, precision: 36, scale: 18 },
@@ -15,6 +27,19 @@ module MoneyAttribute
 
       private
 
+      # Parses arguments for a single-column (amount-only) migration.
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param options [Hash] column options
+      # @option options [Symbol] :column explicit column name override
+      # @option options [Symbol] :type amount type (+:fiat_decimal+,
+      #   +:crypto_decimal+, +:fiat_integer+)
+      # @option options [Boolean] :null whether the column allows NULL
+      # @option options [Object] :default default value for the column
+      # @return [Array(String, Hash)] column name and merged options hash
+      # @raise [ArgumentError] if +precision:+ or +scale:+ are given, or
+      #   type is unrecognized
+      # @api private
       def parse_money_amount_args(accessor, options)
         options ||= {}
         if options.key?(:precision) || options.key?(:scale)
@@ -28,14 +53,24 @@ module MoneyAttribute
 
         config = AMOUNT_CONFIG[options[:type] || :fiat_decimal]
         unless config
-          raise ArgumentError,
-                "Invalid money amount type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
+          raise ArgumentError, "Invalid type #{options[:type]}. Use :crypto_decimal, :fiat_decimal or :fiat_integer"
         end
 
         options = { null: options[:null], default: options[:default] }.compact
         [column, config.merge(options)]
       end
 
+      # Parses arguments for the currency column in a composite migration.
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param options [Hash] currency column options
+      # @option options [Symbol] :column explicit currency column name override
+      # @option options [Integer] :limit string limit for the column
+      # @option options [Boolean] :null whether the column allows NULL
+      # @option options [Object] :default default value for the column
+      # @return [Array(String, Hash)] column name and merged options hash
+      # @raise [ArgumentError] if limit is below {CURRENCY_MIN_LIMIT}
+      # @api private
       def parse_currency_args(accessor, options)
         options ||= {}
         limit = (options[:limit] || CURRENCY_DEFAULT_LIMIT).to_i
@@ -50,6 +85,18 @@ module MoneyAttribute
         [column, { limit:, null: options[:null], default: options[:default] }.compact]
       end
 
+      # Resolves the currency column name for the given accessor.
+      #
+      # Resolution order:
+      # 1. Explicit +column_override+ → returned as-is
+      # 2. Accessor is +:amount+ → +currency+
+      # 3. Accessor ends with +_amount+ → strips suffix and appends +_currency+
+      # 4. Otherwise → +<accessor>_currency+
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param column_override [Symbol, String, nil] explicit column name
+      # @return [String] the resolved currency column name
+      # @api private
       def currency_column_name(accessor, column_override)
         return column_override.to_s if column_override
 
@@ -60,6 +107,18 @@ module MoneyAttribute
         "#{radical}_currency"
       end
 
+      # Parses arguments for a composite (amount + currency) migration.
+      #
+      # Delegates to {#parse_money_amount_args} and {#parse_currency_args}
+      # using the nested +:amount+ and +:currency+ option keys.
+      #
+      # @param accessor [Symbol, String] the money attribute name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options
+      # @option options [Hash] :currency currency column options
+      # @return [Array(String, String, Hash, Hash)] amount column name,
+      #   currency column name, amount options, currency options
+      # @api private
       def parse_money_args(accessor, options = {})
         amount_column, amount_options = parse_money_amount_args(accessor, options[:amount])
         currency_column, currency_options = parse_currency_args(accessor, options[:currency])

data/lib/money_attribute/migration_extensions/schema_statements.rb

@@ -4,32 +4,112 @@ require_relative 'helper'
 
 module MoneyAttribute
   module MigrationExtensions
-    # :nodoc:
+    # Migration helper methods for +ActiveRecord::Migration+.
+    #
+    # Provides reversible methods to add and remove money attribute columns
+    # from within a +change+ migration block.
+    #
+    # @example Adding a composite money attribute
+    #   class AddPriceToProducts < ActiveRecord::Migration[8.0]
+    #     def change
+    #       add_money_attribute :products, :price
+    #     end
+    #   end
+    #
+    # @example Adding a single-column money amount
+    #   class AddDiscountToProducts < ActiveRecord::Migration[8.0]
+    #     def change
+    #       add_money_amount :products, :discount, type: :fiat_integer
+    #     end
+    #   end
     module SchemaStatements
       include Helper
 
+      # Adds an amount column and a currency column for a composite money attribute.
+      #
+      # The amount column type is determined by the +:type+ option inside
+      # +amount: { type: }+ (defaults to +:fiat_decimal+). The currency column
+      # is a string with a configurable limit.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options
+      #   (+:column+, +:type+, +:null+, +:default+)
+      # @option options [Hash] :currency currency column options
+      #   (+:column+, +:limit+, +:null+, +:default+)
+      # @return [void]
+      #
+      # @example Default naming and type
+      #   add_money_attribute :products, :price
+      #   # => add_column :products, :price, :decimal, precision: 20, scale: 4
+      #   # => add_column :products, :price_currency, :string, limit: 20
+      #
+      # @example Custom columns and integer type
+      #   add_money_attribute :products, :price,
+      #     amount: { column: :base_price, type: :fiat_integer },
+      #     currency: { column: :base_currency, limit: 3 }
       def add_money_attribute(table_name, accessor, options = {})
-        amount_col, currency_col, amount_opts, currency_opts = parse_money_args(accessor, options)
+        amount_column, currency_column, amount_opts, currency_opts = parse_money_args(accessor, options)
 
         type = amount_opts.delete(:type)
-        add_column(table_name, amount_col, type, **amount_opts)
-        add_column(table_name, currency_col, :string, **currency_opts)
+        add_column(table_name, amount_column, type, **amount_opts)
+        add_column(table_name, currency_column, :string, **currency_opts)
       end
 
+      # Removes the amount and currency columns for a composite money attribute.
+      #
+      # Accepts the same +:amount+ and +:currency+ options as
+      # {#add_money_attribute} to identify the columns.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] migration options
+      # @option options [Hash] :amount amount column options (+:column+)
+      # @option options [Hash] :currency currency column options (+:column+)
+      # @return [void]
       def remove_money_attribute(table_name, accessor, options = {})
-        amount_col, currency_col, = parse_money_args(accessor, options)
+        amount_column, currency_column, = parse_money_args(accessor, options)
 
-        remove_column(table_name, amount_col)
-        remove_column(table_name, currency_col)
+        remove_column(table_name, amount_column)
+        remove_column(table_name, currency_column)
       end
 
+      # Adds a single amount column for a fixed-currency money attribute.
+      #
+      # No currency column is created — the application default currency is
+      # used for all rows.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] column options
+      # @option options [Symbol] :column explicit column name override
+      # @option options [Symbol] :type amount type (+:fiat_decimal+,
+      #   +:crypto_decimal+, +:fiat_integer+)
+      # @option options [Boolean] :null whether the column allows NULL
+      # @option options [Object] :default default value for the column
+      # @return [void]
+      #
+      # @example Default naming and type
+      #   add_money_amount :products, :discount
+      #   # => add_column :products, :discount, :decimal, precision: 20, scale: 4
+      #
+      # @example Integer column with explicit name
+      #   add_money_amount :products, :bonus, column: :bonus_cents, type: :fiat_integer
       def add_money_amount(table_name, accessor, options = {})
-        amount_col, amount_opts = parse_money_amount_args(accessor, options)
+        amount_column, amount_opts = parse_money_amount_args(accessor, options)
 
         type = amount_opts.delete(:type)
-        add_column(table_name, amount_col, type, **amount_opts)
+        add_column(table_name, amount_column, type, **amount_opts)
       end
 
+      # Removes the amount column for a fixed-currency money attribute.
+      #
+      # @param table_name [Symbol, String] the table to alter
+      # @param accessor [Symbol, String] the money attribute accessor name
+      # @param options [Hash] column options
+      # @option options [Symbol] :column explicit column name override
+      # @return [void]
       def remove_money_amount(table_name, accessor, options = {})
         remove_column(table_name, (options[:column] || accessor).to_s)
       end