money_attribute 1.2.0 → 1.3.0

data/lib/money_attribute/attribute_spec_registry.rb

@@ -4,30 +4,41 @@ require 'concurrent/map'
 
 module MoneyAttribute
   # Stores money attribute metadata on the model class.
+  #
+  # Holds a per-model registry of {AttributeSpec} objects plus derived caches
+  # (name set, regex patterns) populated lazily on first access.
+  #
+  # @api private
   module AttributeSpecRegistry
     extend ActiveSupport::Concern
 
     REGISTRY = Concurrent::Map.new
+    PATTERNS = Concurrent::Map.new
+    QUERY_PLANS = Concurrent::Map.new
 
     class_methods do
       # Registers a money attribute spec for the current model class.
       #
       # @param name [Symbol, String] the attribute name
       # @param kind [Symbol] +:composite+ or +:single+
-      # @param amount_col [Symbol, String] the amount column name
-      # @param currency_col [Symbol, String, nil] the currency column name (composite only)
+      # @param amount_column [Symbol, String] the amount column name
+      # @param currency_column [Symbol, String, nil] the currency column name (composite only)
       # @param amount_type [Symbol, nil] +:integer+ or +:decimal+
       # @return [AttributeSpec]
-      def register_money_attribute_spec(name, kind:, amount_col:, currency_col: nil, amount_type: nil)
+      # @api private
+      def register_money_attribute_spec(name, kind:, amount_column:, currency_column: nil, amount_type: nil)
         spec = MoneyAttribute::AttributeSpec.new(
           name: name.to_s,
           kind: kind,
-          amount_col: amount_col.to_s,
-          currency_col: currency_col&.to_s,
+          amount_column: amount_column.to_s,
+          currency_column: currency_column&.to_s,
           amount_type: amount_type
         )
 
         money_attribute_specs[spec.name] = spec
+        PATTERNS.delete(:"#{self}_name_set")
+        PATTERNS.delete(:"#{self}_name_pattern")
+        QUERY_PLANS.delete(self)
         spec
       end
 
@@ -35,6 +46,7 @@ module MoneyAttribute
       #
       # @param name [Symbol, String] the attribute name
       # @return [AttributeSpec, nil]
+      # @api private
       def money_attribute_spec(name)
         REGISTRY[self]&.fetch(name.to_s, nil)
       end
@@ -42,9 +54,55 @@ module MoneyAttribute
       # Returns the registry hash for the current model class.
       #
       # @return [Hash{String => AttributeSpec}]
+      # @api private
       def money_attribute_specs
         REGISTRY.fetch_or_store(self) { {} }
       end
+
+      # Returns a frozen Set of registered money attribute names.
+      #
+      # @return [Set<String>]
+      # @api private
+      def money_attribute_names_set
+        PATTERNS.fetch_or_store(:"#{self}_name_set") { money_attribute_specs.keys.to_set.freeze }
+      end
+
+      # Returns a pre-compiled regex matching any registered money attribute name.
+      #
+      # @return [Regexp]
+      # @api private
+      def money_attribute_name_pattern
+        PATTERNS.fetch_or_store(:"#{self}_name_pattern") do
+          names = money_attribute_specs.keys.map { |n| Regexp.escape(n) }
+          /\b(#{names.join('|')})\b/i
+        end
+      end
+    end
+
+    class_methods do
+      # Returns whether the model has a registered money attribute.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [Boolean]
+      def money_attribute?(name)
+        !money_attribute_spec(name).nil?
+      end
+
+      # Returns the storage mode for a registered money attribute.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @return [Symbol, nil] +:composite+, +:single+, or +nil+
+      def money_attribute_kind(name)
+        money_attribute_spec(name)&.kind
+      end
+
+      # Returns the compiled string-query cache for the current model class.
+      #
+      # @return [Concurrent::Map]
+      # @api private
+      def money_attribute_query_plan_cache
+        QUERY_PLANS.fetch_or_store(self) { Concurrent::Map.new }
+      end
     end
   end
 end

data/lib/money_attribute/column_type_validations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MoneyAttribute
+  # Shared column-type validation for the +money_attribute+ and +money_amount+
+  # macros.
+  #
+  # Included by {Macro::CompositeClassMethods} and {MoneyAmount}. Raises when a
+  # backing column uses a type that cannot store a money amount or currency code.
+  #
+  # @api private
+  module ColumnTypeValidations
+    VALID_AMOUNT_TYPES = %i[integer bigint decimal].freeze
+    VALID_CURRENCY_TYPES = %i[string text].freeze
+
+    # Validates that a column can store a money amount.
+    #
+    # @param attr_name [Symbol, String] the money attribute accessor name
+    # @param column_name [Symbol, String] the amount column name
+    # @param column [ActiveRecord::ConnectionAdapters::Column] the column metadata
+    # @return [void]
+    # @raise [ArgumentError] if the column type is not numeric
+    # @api private
+    def assert_valid_amount_column!(attr_name, column_name, column)
+      return if VALID_AMOUNT_TYPES.include?(column.type)
+
+      raise ArgumentError,
+            "`:#{attr_name}` amount column `#{column_name}` must be a numeric type " \
+            "(integer, bigint, or decimal), got `#{column.type}`"
+    end
+
+    # Validates that a column can store a currency code.
+    #
+    # @param attr_name [Symbol, String] the money attribute accessor name
+    # @param column_name [Symbol, String] the currency column name
+    # @param column [ActiveRecord::ConnectionAdapters::Column] the column metadata
+    # @return [void]
+    # @raise [ArgumentError] if the column type is not string-like
+    # @api private
+    def assert_valid_currency_column!(attr_name, column_name, column)
+      return if VALID_CURRENCY_TYPES.include?(column.type)
+
+      raise ArgumentError,
+            "`:#{attr_name}` currency column `#{column_name}` must be a string type " \
+            "(string or text), got `#{column.type}`"
+    end
+  end
+end

data/lib/money_attribute/converter.rb

@@ -1,27 +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
     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 `Money` value.
+    # 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, currency)
-      when String               then Money.parse(amount, currency)
+      when String               then Money.parse(amount, default_currency: currency)
       else raise ArgumentError, "Cannot convert #{amount.inspect} (#{amount.class}) to Money"
       end
     end

data/lib/money_attribute/core_ext/numeric.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
-# :nodoc:
+# 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)
 
-  def to_money(currency = MoneyAttribute.default_currency) = Money.parse(self, currency)
+  # 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, default_currency: currency)
 end

data/lib/money_attribute/form_builder_extension.rb

@@ -1,9 +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 money attribute.
+    # 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
@@ -12,7 +42,22 @@ module MoneyAttribute
                                { id: field_id(method) }.merge(options))
     end
 
-    # Renders a number input for a single-column money attribute.
+    # 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,13 +1,32 @@
 # 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
+      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)
@@ -20,6 +39,13 @@ module MoneyAttribute
       end
 
       # 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
@@ -34,18 +60,35 @@ module MoneyAttribute
       end
 
       # 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)
-        column = column_for_attribute(mapping[:amount])
+        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_col: mapping[:amount],
-          currency_col: mapping[:currency],
-          amount_type: %i[integer bigint].include?(column.type) ? :integer : :decimal
+          amount_column: mapping[:amount],
+          currency_column: mapping[:currency],
+          amount_type: %i[integer bigint].include?(amount_column.type) ? :integer : :decimal
         )
       end
 
       # 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?
@@ -55,11 +98,57 @@ module MoneyAttribute
               "Expected: #{mapping.values.join(', ')}, " \
               "Found: #{attribute_names.join(', ')}"
       end
+
+      # Normalizes migration-style column options to the legacy mapping format.
+      #
+      # @param mapping [Hash] the user-supplied +mapping:+ option
+      # @param amount [Hash, nil] migration-style amount options
+      # @param currency [Hash, nil] migration-style currency options
+      # @return [Hash] normalized column mapping
+      # @raise [ArgumentError] if options are ambiguous or unsupported
+      # @api private
+      def normalize_mapping(mapping, amount, currency)
+        mapping = mapping.compact
+        nested = { amount:, currency: }.compact
+        conflicts = mapping.keys & nested.keys
+        unless conflicts.empty?
+          raise ArgumentError, "Specify #{conflicts.join(', ')} using either mapping: or nested options, not both"
+        end
+
+        nested.each do |key, options|
+          mapping[key] = normalize_nested_column(key, options)
+        end
+
+        mapping
+      end
+
+      def normalize_nested_column(key, options)
+        return options[:column] if options.is_a?(Hash) && options.keys == [:column] && options[:column]
+
+        raise ArgumentError, "#{key}: must be a hash containing only a non-empty :column option"
+      end
     end
 
     class_methods do
       # Declares a composite money attribute on the model.
-      def money_attribute(name, mapping: {})
+      #
+      # 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+)
+      # @param amount [Hash, nil] migration-style amount options (+:column+ only)
+      # @param currency [Hash, nil] migration-style currency options (+:column+ only)
+      # @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: {}, amount: nil, currency: nil)
+        mapping = normalize_mapping(mapping, amount, currency)
         mapping = resolve_mapping(name, mapping)
         spec = register_composite_spec(name, mapping)
 

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)
@@ -35,6 +60,17 @@ module MoneyAttribute
         [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
@@ -49,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
 
@@ -59,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