cmdx 1.0.1 → 1.1.0

data/lib/cmdx/coercions/boolean.rb

@@ -2,53 +2,34 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Boolean type (true/false).
+    # Coercion class for converting values to booleans.
     #
-    # The Boolean coercion converts parameter values to true or false
-    # based on string pattern matching for common boolean representations.
-    # It handles various textual representations of true and false values.
-    #
-    # @example Basic boolean coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :send_email, type: :boolean, default: true
-    #     optional :is_urgent, type: :boolean, default: false
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Boolean.call("true")     # => true
-    #   Coercions::Boolean.call("yes")      # => true
-    #   Coercions::Boolean.call("1")        # => true
-    #   Coercions::Boolean.call("false")    # => false
-    #   Coercions::Boolean.call("no")       # => false
-    #   Coercions::Boolean.call("0")        # => false
-    #   Coercions::Boolean.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Boolean
+    # This coercion handles conversion of various string representations to
+    # boolean values, supporting common true/false variations like "yes/no",
+    # "1/0", and "t/f".
+    class Boolean < Coercion
 
-      # Pattern matching false-like values (case insensitive)
-      # @return [Regexp] regex for falsey string values
       FALSEY = /^(false|f|no|n|0)$/i
-
-      # Pattern matching true-like values (case insensitive)
-      # @return [Regexp] regex for truthy string values
       TRUTHY = /^(true|t|yes|y|1)$/i
 
-      module_function
-
-      # Coerce a value to Boolean.
+      # Converts the given value to a boolean.
+      #
+      # @param value [Object] the value to convert to a boolean
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Boolean] the converted boolean value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a boolean
       #
-      # @param value [Object] value to coerce to boolean
-      # @param _options [Hash] coercion options (unused)
-      # @return [Boolean] coerced boolean value (true or false)
-      # @raise [CoercionError] if value cannot be coerced to boolean
+      # @example Converting truthy values
+      #   Coercions::Boolean.call('true') #=> true
+      #   Coercions::Boolean.call('yes') #=> true
+      #   Coercions::Boolean.call('1') #=> true
       #
-      # @example
-      #   Coercions::Boolean.call("yes")    # => true
-      #   Coercions::Boolean.call("False")  # => false
-      #   Coercions::Boolean.call("1")      # => true
-      #   Coercions::Boolean.call("0")      # => false
+      # @example Converting falsey values
+      #   Coercions::Boolean.call('false') #=> false
+      #   Coercions::Boolean.call('no') #=> false
+      #   Coercions::Boolean.call('0') #=> false
       def call(value, _options = {})
         case value.to_s.downcase
         when FALSEY then false

data/lib/cmdx/coercions/complex.rb

@@ -2,41 +2,28 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Complex type.
+    # Coercion class for converting values to complex numbers.
     #
-    # The Complex coercion converts parameter values to Complex number objects
-    # using Ruby's built-in Complex() method, with proper error handling
-    # for values that cannot be converted to complex numbers.
-    #
-    # @example Basic complex coercion
-    #   class MathTask < CMDx::Task
-    #     required :complex_number, type: :complex
-    #     optional :coefficient, type: :complex, default: Complex(1, 0)
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Complex.call("1+2i")      # => (1+2i)
-    #   Coercions::Complex.call("3-4i")      # => (3-4i)
-    #   Coercions::Complex.call(5)           # => (5+0i)
-    #   Coercions::Complex.call("invalid")   # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Complex
-
-      module_function
+    # This coercion handles conversion of various types to complex numbers,
+    # including strings, integers, floats, and other numeric types.
+    class Complex < Coercion
 
-      # Coerce a value to Complex.
+      # Converts the given value to a complex number.
+      #
+      # @param value [Object] the value to convert to a complex number
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Complex] the converted complex number value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a complex number
       #
-      # @param value [Object] value to coerce to complex number
-      # @param _options [Hash] coercion options (unused)
-      # @return [Complex] coerced complex number value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric values
+      #   Coercions::Complex.call(5) #=> (5+0i)
+      #   Coercions::Complex.call(3.14) #=> (3.14+0i)
       #
-      # @example
-      #   Coercions::Complex.call("1+2i")    # => (1+2i)
-      #   Coercions::Complex.call(42)        # => (42+0i)
-      #   Coercions::Complex.call("3.5-2i")  # => (3.5-2i)
+      # @example Converting string representations
+      #   Coercions::Complex.call("2+3i") #=> (2+3i)
+      #   Coercions::Complex.call("1-2i") #=> (1-2i)
       def call(value, _options = {})
         Complex(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/date.rb

@@ -2,54 +2,35 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Date type.
+    # Coercion class for converting values to Date objects.
     #
-    # The Date coercion converts parameter values to Date objects
-    # with support for date parsing, custom format strings, and
-    # automatic handling of date-like objects.
-    #
-    # @example Basic date coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_date, type: :date
-    #     optional :delivery_date, type: :date, format: "%Y-%m-%d"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Date.call("2023-12-25")                    # => Date object
-    #   Coercions::Date.call("25/12/2023", format: "%d/%m/%Y") # Custom format
-    #   Coercions::Date.call(Time.now)                        # => Date (from Time)
-    #   Coercions::Date.call("invalid")                       # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Date
+    # This coercion handles conversion of various types to Date objects, with support
+    # for custom date formats and automatic detection of date-like objects.
+    class Date < Coercion
 
-      # Date-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent date-like objects
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
-      module_function
-
-      # Coerce a value to Date.
+      # Converts the given value to a Date object.
+      #
+      # @param value [Object] the value to convert to a Date
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom date format for parsing
+      #
+      # @return [Date] the converted Date object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a Date
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as Date)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using Date.parse)
+      # @example Converting a string with default parsing
+      #   Coercions::Date.call('2023-12-25') #=> #<Date: 2023-12-25>
       #
-      # @param value [Object] value to coerce to date
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom date format string
-      # @return [Date] coerced date value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with custom format
+      #   Coercions::Date.call('25/12/2023', strptime: '%d/%m/%Y') #=> #<Date: 2023-12-25>
       #
-      # @example
-      #   Coercions::Date.call("2023-12-25")                      # => Date
-      #   Coercions::Date.call("25/12/2023", format: "%d/%m/%Y")  # => Date with custom format
-      #   Coercions::Date.call(Time.now)                          # => Date from Time
+      # @example Converting existing date-like objects
+      #   Coercions::Date.call(DateTime.now) #=> #<Date: 2023-12-25>
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::Date.strptime(value, options[:format]) if options[:format]
+        return ::Date.strptime(value, options[:strptime]) if options[:strptime]
 
         ::Date.parse(value)
       rescue TypeError, ::Date::Error

data/lib/cmdx/coercions/date_time.rb

@@ -2,54 +2,37 @@
 
 module CMDx
   module Coercions
-    # Coerces values to DateTime type.
+    # Coercion class for converting values to DateTime objects.
     #
-    # The DateTime coercion converts parameter values to DateTime objects
-    # with support for datetime parsing, custom format strings, and
-    # automatic handling of date/time-like objects.
-    #
-    # @example Basic datetime coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_datetime, type: :date_time
-    #     optional :delivery_datetime, type: :date_time, format: "%Y-%m-%d %H:%M:%S"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::DateTime.call("2023-12-25T14:30:00")                    # => DateTime object
-    #   Coercions::DateTime.call("25/12/2023 2:30 PM", format: "%d/%m/%Y %l:%M %p") # Custom format
-    #   Coercions::DateTime.call(Time.now)                                 # => DateTime (from Time)
-    #   Coercions::DateTime.call("invalid")                                # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module DateTime
+    # This coercion handles conversion of various types to DateTime objects,
+    # with support for custom date/time formats and automatic detection of
+    # analog types (Date, DateTime, Time).
+    class DateTime < Coercion
 
-      # DateTime-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent datetime-like objects
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
-      module_function
-
-      # Coerce a value to DateTime.
+      # Converts the given value to a DateTime object.
+      #
+      # @param value [Object] the value to convert to a DateTime
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom format string for parsing
+      #
+      # @return [DateTime] the converted DateTime object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a DateTime
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as-is)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using DateTime.parse)
+      # @example Converting a date string
+      #   Coercions::DateTime.call('2023-12-25') #=> #<DateTime: 2023-12-25T00:00:00+00:00>
       #
-      # @param value [Object] value to coerce to datetime
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom datetime format string
-      # @return [DateTime] coerced datetime value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with a custom format
+      #   Coercions::DateTime.call('25/12/2023', strptime: '%d/%m/%Y') #=> #<DateTime: 2023-12-25T00:00:00+00:00>
       #
-      # @example
-      #   Coercions::DateTime.call("2023-12-25T14:30:00")                      # => DateTime
-      #   Coercions::DateTime.call("25/12/2023 14:30", format: "%d/%m/%Y %H:%M") # => DateTime with custom format
-      #   Coercions::DateTime.call(Time.now)                                    # => DateTime from Time
+      # @example Passing through existing DateTime objects
+      #   dt = DateTime.now
+      #   Coercions::DateTime.call(dt) #=> dt (unchanged)
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::DateTime.strptime(value, options[:format]) if options[:format]
+        return ::DateTime.strptime(value, options[:strptime]) if options[:strptime]
 
         ::DateTime.parse(value)
       rescue TypeError, ::Date::Error

data/lib/cmdx/coercions/float.rb

@@ -2,44 +2,31 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Float type.
+    # Coercion class for converting values to floats.
     #
-    # The Float coercion converts parameter values to Float objects
-    # using Ruby's built-in Float() method, with proper error handling
-    # for values that cannot be converted to floating-point numbers.
-    #
-    # @example Basic float coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :price, type: :float
-    #     optional :discount_rate, type: :float, default: 0.0
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Float.call("123.45")   # => 123.45
-    #   Coercions::Float.call("1.5e2")    # => 150.0 (scientific notation)
-    #   Coercions::Float.call(42)         # => 42.0
-    #   Coercions::Float.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Float
-
-      module_function
+    # This coercion handles conversion of various types to float values using
+    # Ruby's built-in Float() method.
+    class Float < Coercion
 
-      # Coerce a value to Float.
+      # Converts the given value to a float.
+      #
+      # @param value [Object] the value to convert to a float
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Float] the converted float value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a float
       #
-      # @param value [Object] value to coerce to float
-      # @param _options [Hash] coercion options (unused)
-      # @return [Float] coerced float value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric strings
+      #   Coercions::Float.call("3.14") #=> 3.14
+      #   Coercions::Float.call("42") #=> 42.0
       #
-      # @example
-      #   Coercions::Float.call("123.45")  # => 123.45
-      #   Coercions::Float.call(42)        # => 42.0
-      #   Coercions::Float.call("1e3")     # => 1000.0
+      # @example Converting other numeric types
+      #   Coercions::Float.call(42) #=> 42.0
+      #   Coercions::Float.call(3.14) #=> 3.14
       def call(value, _options = {})
         Float(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, RangeError, TypeError
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",
           type: "float",

data/lib/cmdx/coercions/hash.rb

@@ -2,47 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Hash type.
+    # Coercion class for converting values to hashes.
     #
-    # The Hash coercion converts parameter values to Hash objects
-    # with support for various input formats including JSON strings,
-    # arrays (converted to hash), and Rails parameters.
-    #
-    # @example Basic hash coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :metadata, type: :hash, default: {}
-    #     optional :options, type: :hash
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Hash.call({a: 1})              # => {a: 1}
-    #   Coercions::Hash.call('{"a":1,"b":2}')     # => {"a"=>1, "b"=>2} (JSON)
-    #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a=>1, :b=>2} (Array)
-    #   Coercions::Hash.call("invalid")           # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Hash
-
-      extend self
+    # This coercion handles conversion of various types to hashes, with special
+    # handling for JSON-formatted strings that start with "{" and array-to-hash
+    # conversion using array splatting.
+    class Hash < Coercion
 
-      # Coerce a value to Hash.
+      # Converts the given value to a hash.
       #
-      # Supports multiple input formats:
-      # - Hash objects (returned as-is)
-      # - ActionController::Parameters (returned as-is)
-      # - JSON strings starting with '{' (parsed as JSON)
-      # - Arrays (converted using Hash[*array])
+      # @param value [Object] the value to convert to a hash
+      # @param _options [Hash] optional configuration (currently unused)
       #
-      # @param value [Object] value to coerce to hash
-      # @param _options [Hash] coercion options (unused)
-      # @return [Hash] coerced hash value
-      # @raise [CoercionError] if coercion fails
+      # @return [Hash] the converted hash value
       #
-      # @example
-      #   Coercions::Hash.call({key: "value"})      # => {key: "value"}
-      #   Coercions::Hash.call('{"a": 1}')          # => {"a" => 1}
-      #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a => 1, :b => 2}
+      # @raise [CoercionError] if the value cannot be converted to a hash
+      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
+      # @raise [ArgumentError] if array cannot be converted to hash pairs
+      # @raise [TypeError] if the value type is not supported
+      #
+      # @example Converting a JSON string
+      #   Coercions::Hash.call('{"a": 1, "b": 2}') #=> {"a" => 1, "b" => 2}
+      #
+      # @example Converting an array to hash
+      #   Coercions::Hash.call(["a", 1, "b", 2]) #=> {"a" => 1, "b" => 2}
+      #
+      # @example Passing through existing hashes
+      #   Coercions::Hash.call({"key" => "value"}) #=> {"key" => "value"}
       def call(value, _options = {})
         case value.class.name
         when "Hash", "ActionController::Parameters"
@@ -60,11 +46,6 @@ module CMDx
 
       private
 
-      # Raise a standardized coercion error.
-      #
-      # @return [void]
-      # @raise [CoercionError] always raises coercion error
-      # @api private
       def raise_coercion_error!
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",

data/lib/cmdx/coercions/integer.rb

@@ -2,45 +2,32 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Integer type.
+    # Coercion class for converting values to integers.
     #
-    # The Integer coercion converts parameter values to Integer objects
-    # using Ruby's built-in Integer() method, with proper error handling
-    # for values that cannot be converted.
-    #
-    # @example Basic integer coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_id, type: :integer
-    #     optional :quantity, type: :integer, default: 1
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Integer.call("123")     # => 123
-    #   Coercions::Integer.call("0x10")    # => 16 (hex)
-    #   Coercions::Integer.call("0b1010")  # => 10 (binary)
-    #   Coercions::Integer.call(45.7)      # => 45 (truncated)
-    #   Coercions::Integer.call("invalid") # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Integer
-
-      module_function
+    # This coercion handles conversion of various types to integers using Ruby's
+    # built-in Integer() method, which provides strict type conversion.
+    class Integer < Coercion
 
-      # Coerce a value to Integer.
+      # Converts the given value to an integer.
+      #
+      # @param value [Object] the value to convert to an integer
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Integer] the converted integer value
+      #
+      # @raise [CoercionError] if the value cannot be converted to an integer
       #
-      # @param value [Object] value to coerce to integer
-      # @param _options [Hash] coercion options (unused)
-      # @return [Integer] coerced integer value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric strings
+      #   Coercions::Integer.call("123") #=> 123
+      #   Coercions::Integer.call("-456") #=> -456
       #
-      # @example
-      #   Coercions::Integer.call("123")   # => 123
-      #   Coercions::Integer.call(45.9)    # => 45
-      #   Coercions::Integer.call("0xFF")  # => 255
+      # @example Converting other numeric types
+      #   Coercions::Integer.call(123.45) #=> 123
+      #   Coercions::Integer.call(Time.now) #=> 1672574400 (timestamp)
+      #   Coercions::Integer.call(Complex(42, 0)) #=> 42
       def call(value, _options = {})
         Integer(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, FloatDomainError, RangeError, TypeError # rubocop:disable Lint/ShadowedException
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_an",
           type: "integer",

data/lib/cmdx/coercions/rational.rb

@@ -2,44 +2,32 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Rational type.
+    # Coercion class for converting values to rational numbers.
     #
-    # The Rational coercion converts parameter values to Rational number objects
-    # using Ruby's built-in Rational() method, with proper error handling
-    # for values that cannot be converted to rational numbers.
-    #
-    # @example Basic rational coercion
-    #   class MathTask < CMDx::Task
-    #     required :fraction, type: :rational
-    #     optional :ratio, type: :rational, default: Rational(1, 2)
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Rational.call("1/2")      # => (1/2)
-    #   Coercions::Rational.call("3/4")      # => (3/4)
-    #   Coercions::Rational.call(0.5)        # => (1/2)
-    #   Coercions::Rational.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Rational
-
-      module_function
+    # This coercion handles conversion of various types to rational numbers,
+    # using Ruby's built-in Rational() method for type conversion.
+    class Rational < Coercion
 
-      # Coerce a value to Rational.
+      # Converts the given value to a rational number.
+      #
+      # @param value [Object] the value to convert to a rational number
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Rational] the converted rational value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a rational number
+      #
+      # @example Converting a string fraction
+      #   Coercions::Rational.call('1/2') #=> (1/2)
       #
-      # @param value [Object] value to coerce to rational number
-      # @param _options [Hash] coercion options (unused)
-      # @return [Rational] coerced rational number value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting an integer
+      #   Coercions::Rational.call(5) #=> (5/1)
       #
-      # @example
-      #   Coercions::Rational.call("1/2")    # => (1/2)
-      #   Coercions::Rational.call(0.75)     # => (3/4)
-      #   Coercions::Rational.call("3.5")    # => (7/2)
+      # @example Converting a float
+      #   Coercions::Rational.call(0.25) #=> (1/4)
       def call(value, _options = {})
         Rational(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, FloatDomainError, RangeError, TypeError, ZeroDivisionError # rubocop:disable Lint/ShadowedException
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",
           type: "rational",

data/lib/cmdx/coercions/string.rb

@@ -2,41 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to String type.
+    # Coercion class for converting values to strings.
     #
-    # The String coercion converts parameter values to String objects
-    # using Ruby's built-in String() method, which handles various
-    # input types safely.
-    #
-    # @example Basic string coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_id, type: :string
-    #     optional :notes, type: :string
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::String.call(123)        # => "123"
-    #   Coercions::String.call(:symbol)    # => "symbol"
-    #   Coercions::String.call(true)       # => "true"
-    #   Coercions::String.call(nil)        # => ""
-    #   Coercions::String.call([1, 2])     # => "12" (array to_s)
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module String
-
-      module_function
+    # This coercion handles conversion of various types to strings using Ruby's
+    # built-in String() method, which provides consistent string conversion
+    # behavior across different object types.
+    class String < Coercion
 
-      # Coerce a value to String.
+      # Converts the given value to a string.
+      #
+      # @param value [Object] the value to convert to a string
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [String] the converted string value
+      #
+      # @raise [TypeError] if the value cannot be converted to a string
+      #
+      # @example Converting numbers
+      #   Coercions::String.call(123) #=> "123"
+      #   Coercions::String.call(45.67) #=> "45.67"
       #
-      # @param value [Object] value to coerce to string
-      # @param _options [Hash] coercion options (unused)
-      # @return [String] coerced string value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting symbols and nil
+      #   Coercions::String.call(:symbol) #=> "symbol"
+      #   Coercions::String.call(nil) #=> ""
       #
-      # @example
-      #   Coercions::String.call(123)    # => "123"
-      #   Coercions::String.call(:test)  # => "test"
+      # @example Converting boolean values
+      #   Coercions::String.call(true) #=> "true"
+      #   Coercions::String.call(false) #=> "false"
       def call(value, _options = {})
         String(value)
       end