cmdx 1.0.1 → 1.1.1

data/lib/cmdx/chain_serializer.rb

@@ -1,165 +1,53 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Chain serialization utility for converting Chain objects to hash representations.
-  #
-  # The ChainSerializer module provides functionality to serialize Chain instances
-  # into structured hash representations suitable for inspection, logging,
-  # debugging, and data interchange. It creates comprehensive data structures
-  # that include chain metadata and all associated task results.
-  #
-  # @example Basic chain serialization
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   chain = result.chain
-  #
-  #   ChainSerializer.call(chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   runtime: 0.5,
-  #   #   results: [
-  #   #     {
-  #   #       class: "ProcessOrderTask",
-  #   #       type: "Task",
-  #   #       index: 0,
-  #   #       id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #       chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #       tags: [],
-  #   #       state: "complete",
-  #   #       status: "success",
-  #   #       outcome: "success",
-  #   #       metadata: {},
-  #   #       runtime: 0.5
-  #   #     }
-  #   #   ]
-  #   # }
-  #
-  # @example Chain with multiple tasks
-  #   class ComplexTask < CMDx::Task
-  #     def call
-  #       SubTask1.call(context)
-  #       SubTask2.call(context)
-  #     end
-  #   end
-  #
-  #   result = ComplexTask.call
-  #   chain = result.chain
-  #
-  #   ChainSerializer.call(chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   runtime: 1.2,
-  #   #   results: [
-  #   #     { class: "ComplexTask", index: 0, state: "complete", status: "success", ... },
-  #   #     { class: "SubTask1", index: 1, state: "complete", status: "success", ... },
-  #   #     { class: "SubTask2", index: 2, state: "complete", status: "success", ... }
-  #   #   ]
-  #   # }
-  #
-  # @example Failed chain serialization
-  #   failed_result = FailingTask.call
-  #   failed_chain = failed_result.chain
-  #
-  #   ChainSerializer.call(failed_chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "interrupted",
-  #   #   status: "failed",
-  #   #   outcome: "failed",
-  #   #   runtime: 0.1,
-  #   #   results: [
-  #   #     {
-  #   #       class: "FailingTask",
-  #   #       state: "interrupted",
-  #   #       status: "failed",
-  #   #       outcome: "failed",
-  #   #       metadata: { reason: "Something went wrong" },
-  #   #       runtime: 0.1,
-  #   #       ...
-  #   #     }
-  #   #   ]
-  #   # }
-  #
-  # @see CMDx::Chain Chain execution context and result tracking
-  # @see CMDx::ResultSerializer Individual result serialization
-  # @see CMDx::ChainInspector Human-readable chain formatting
+  # Serialization module for converting chain objects to hash representation.
+  #
+  # ChainSerializer provides functionality to serialize chain objects into a
+  # standardized hash format that includes essential metadata about the chain
+  # execution including unique identification, execution state, status, outcome,
+  # runtime, and all contained task results. The serialized format is commonly
+  # used for debugging, logging, introspection, and data exchange throughout
+  # the task execution pipeline.
   module ChainSerializer
 
     module_function
 
-    # Converts a Chain object to a hash representation.
+    # Serializes a chain object into a hash representation.
     #
-    # Serializes a Chain instance into a structured hash containing chain metadata
-    # and all associated task results. The chain-level data is derived from the
-    # first result in the collection, while all individual results are included
-    # in their full serialized form.
+    # Converts a chain instance into a standardized hash format containing
+    # key metadata about the chain's execution context and all contained results.
+    # The serialization includes information delegated from the first result in
+    # the chain (state, status, outcome, runtime) along with the chain's unique
+    # identifier and complete collection of task results converted to hashes.
     #
-    # @param chain [CMDx::Chain] The chain object to serialize
-    # @return [Hash] Structured hash representation of the chain and all results
+    # @param chain [CMDx::Chain] the chain object to serialize
     #
-    # @example Simple chain serialization
-    #   chain = SimpleTask.call.chain
-    #   ChainSerializer.call(chain)
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+    # @return [Hash] a hash containing the chain's metadata and execution information
+    # @option return [String] :id the unique identifier of the chain
+    # @option return [String] :state the execution state delegated from first result
+    # @option return [String] :status the execution status delegated from first result
+    # @option return [String] :outcome the execution outcome delegated from first result
+    # @option return [Float] :runtime the execution runtime in seconds delegated from first result
+    # @option return [Array<Hash>] :results array of serialized result hashes from all tasks in the chain
+    #
+    # @raise [NoMethodError] if the chain doesn't respond to required methods (id, state, status, outcome, runtime, results)
+    #
+    # @example Serialize a workflow chain with multiple tasks
+    #   workflow = DataProcessingWorkflow.call(input: "data")
+    #   ChainSerializer.call(workflow.chain)
+    #   #=> {
+    #   #   id: "def456",
     #   #   state: "complete",
     #   #   status: "success",
     #   #   outcome: "success",
-    #   #   runtime: 0.1,
+    #   #   runtime: 0.123,
     #   #   results: [
-    #   #     {
-    #   #       class: "SimpleTask",
-    #   #       type: "Task",
-    #   #       index: 0,
-    #   #       id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #       chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #       tags: [],
-    #   #       state: "complete",
-    #   #       status: "success",
-    #   #       outcome: "success",
-    #   #       metadata: {},
-    #   #       runtime: 0.1
-    #   #     }
+    #   #     { index: 0, class: "ValidateDataTask", status: "success", ... },
+    #   #     { index: 1, class: "ProcessDataTask", status: "success", ... },
+    #   #     { index: 2, class: "SaveDataTask", status: "success", ... }
     #   #   ]
     #   # }
-    #
-    # @example Multi-task chain serialization
-    #   class ParentTask < CMDx::Task
-    #     def call
-    #       ChildTask.call(context)
-    #     end
-    #   end
-    #
-    #   chain = ParentTask.call.chain
-    #   ChainSerializer.call(chain)
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "complete",      # From first result (ParentTask)
-    #   #   status: "success",      # From first result (ParentTask)
-    #   #   outcome: "success",     # From first result (ParentTask)
-    #   #   runtime: 0.5,          # From first result (ParentTask)
-    #   #   results: [
-    #   #     { class: "ParentTask", index: 0, ... },
-    #   #     { class: "ChildTask", index: 1, ... }
-    #   #   ]
-    #   # }
-    #
-    # @example Empty chain serialization
-    #   empty_chain = Chain.new
-    #   ChainSerializer.call(empty_chain)
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: nil,
-    #   #   status: nil,
-    #   #   outcome: nil,
-    #   #   runtime: nil,
-    #   #   results: []
-    #   # }
     def call(chain)
       {
         id: chain.id,

data/lib/cmdx/coercion.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Base class for implementing parameter coercion functionality in task processing.
+  #
+  # Coercions are used to convert parameter values from one type to another during
+  # task execution, enabling automatic type conversion and normalization. All coercion
+  # implementations must inherit from this class and implement the abstract call method.
+  class Coercion
+
+    # Executes a coercion by creating a new instance and calling it.
+    #
+    # @param value [Object] the value to be coerced
+    # @param options [Hash] additional options for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UndefinedCallError] when the coercion subclass doesn't implement call
+    # @raise [CoercionError] when coercion fails in subclass implementations
+    #
+    # @example Execute a coercion on a value
+    #   StringCoercion.call(123) #=> "123"
+    #
+    # @example Execute with options
+    #   CustomCoercion.call("value", strict: true) #=> processed_value
+    def self.call(value, options = {})
+      new.call(value, options)
+    end
+
+    # Abstract method that must be implemented by coercion subclasses.
+    #
+    # This method contains the actual coercion logic to convert the input
+    # value to the desired type. Subclasses must override this method
+    # to provide their specific coercion implementation.
+    #
+    # @param value [Object] the value to be coerced (unused in base class)
+    # @param options [Hash] additional options for the coercion (unused in base class)
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UndefinedCallError] always raised in the base class
+    # @raise [CoercionError] when coercion fails in subclass implementations
+    #
+    # @example Implement in a subclass
+    #   class StringCoercion < CMDx::Coercion
+    #     def call(value, _options = {})
+    #       String(value)
+    #     rescue ArgumentError, TypeError
+    #       raise CoercionError, "could not coerce into a string"
+    #     end
+    #   end
+    def call(value, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    end
+
+  end
+end

data/lib/cmdx/coercion_registry.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry for managing parameter type coercion functionality.
+  #
+  # CoercionRegistry provides a centralized system for storing, accessing, and
+  # executing type coercions during task parameter processing. It maintains an
+  # internal registry of coercion type keys mapped to their corresponding coercion
+  # classes or callables, supporting both built-in framework coercions and custom
+  # user-defined coercions for flexible type conversion during task execution.
+  class CoercionRegistry
+
+    # @return [Hash] hash containing coercion type keys and coercion class/callable values
+    attr_reader :registry
+
+    # Creates a new coercion registry with built-in coercion types.
+    #
+    # Initializes the registry with all standard framework coercions including
+    # primitive types (string, integer, float, boolean), date/time types,
+    # collection types (array, hash), numeric types (big_decimal, rational, complex),
+    # and the virtual coercion type for parameter definitions without type conversion.
+    #
+    # @return [CoercionRegistry] a new registry instance with built-in coercions
+    #
+    # @example Create a new coercion registry
+    #   registry = CoercionRegistry.new
+    #   registry.registry.keys
+    #   #=> [:array, :big_decimal, :boolean, :complex, :date, :datetime, :float, :hash, :integer, :rational, :string, :time, :virtual]
+    def initialize
+      @registry = {
+        array: Coercions::Array,
+        big_decimal: Coercions::BigDecimal,
+        boolean: Coercions::Boolean,
+        complex: Coercions::Complex,
+        date: Coercions::Date,
+        datetime: Coercions::DateTime,
+        float: Coercions::Float,
+        hash: Coercions::Hash,
+        integer: Coercions::Integer,
+        rational: Coercions::Rational,
+        string: Coercions::String,
+        time: Coercions::Time,
+        virtual: Coercions::Virtual
+      }
+    end
+
+    # Registers a new coercion type in the registry.
+    #
+    # Adds or overwrites a coercion type mapping in the registry, allowing custom
+    # coercions to be used during task parameter processing. The coercion can be
+    # a class that responds to `call`, a callable object, or a symbol/string
+    # representing a method to invoke on the task instance.
+    #
+    # @param type [Symbol] the coercion type identifier to register
+    # @param coercion [Class, Proc, Symbol, String] the coercion implementation
+    #
+    # @return [CoercionRegistry] self for method chaining
+    #
+    # @example Register a custom coercion class
+    #   registry.register(:temperature, TemperatureCoercion)
+    #
+    # @example Register a coercion proc
+    #   registry.register(:upcase, proc { |value, options| value.to_s.upcase })
+    #
+    # @example Register a method symbol
+    #   registry.register(:custom_parse, :parse_custom_format)
+    def register(type, coercion)
+      registry[type] = coercion
+      self
+    end
+
+    # Executes a coercion by type on the provided value.
+    #
+    # Looks up and executes the coercion implementation for the specified type,
+    # applying it to the provided value with optional configuration. Handles
+    # different coercion implementation types including callable objects,
+    # method symbols/strings, and coercion classes.
+    #
+    # @param task [CMDx::Task] the task instance for context when calling methods
+    # @param type [Symbol] the coercion type to execute
+    # @param value [Object] the value to be coerced
+    # @param options [Hash] additional options passed to the coercion
+    # @option options [Object] any any additional configuration for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UnknownCoercionError] when the specified coercion type is not registered
+    # @raise [CoercionError] when the coercion fails to convert the value
+    #
+    # @example Execute a built-in coercion
+    #   registry.call(task, :integer, "123")
+    #   #=> 123
+    #
+    # @example Execute with options
+    #   registry.call(task, :date, "2024-01-15", format: "%Y-%m-%d")
+    #   #=> #<Date: 2024-01-15>
+    #
+    # @example Handle unknown coercion type
+    #   registry.call(task, :unknown_type, "value")
+    #   #=> raises UnknownCoercionError
+    def call(task, type, value, options = {})
+      raise UnknownCoercionError, "unknown coercion #{type}" unless registry.key?(type)
+
+      case coercion = registry[type]
+      when Symbol, String, Proc
+        task.cmdx_try(coercion, value, options)
+      else
+        coercion.call(value, options)
+      end
+    end
+
+  end
+end

data/lib/cmdx/coercions/array.rb

@@ -2,47 +2,29 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Array type.
+    # Coercion class for converting values to arrays.
     #
-    # The Array coercion converts parameter values to Array objects,
-    # with special handling for JSON-formatted strings and general
-    # array conversion using Ruby's Array() method.
-    #
-    # @example Basic array coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :tags, type: :array, default: []
-    #     optional :item_ids, type: :array
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Array.call([1, 2, 3])      # => [1, 2, 3]
-    #   Coercions::Array.call("hello")        # => ["hello"]
-    #   Coercions::Array.call('["a","b"]')    # => ["a", "b"] (JSON)
-    #   Coercions::Array.call('[1,2,3]')      # => [1, 2, 3] (JSON)
-    #   Coercions::Array.call(nil)            # => []
-    #   Coercions::Array.call(42)             # => [42]
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Array
+    # This coercion handles conversion of various types to arrays, with special
+    # handling for JSON-formatted strings that start with "[".
+    class Array < Coercion
 
-      module_function
-
-      # Coerce a value to Array.
+      # Converts the given value to an array.
+      #
+      # @param value [Object] the value to convert to an array
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Array] the converted array value
       #
-      # If the value is a JSON-formatted string (starts with '['), it will
-      # be parsed as JSON. Otherwise, it uses Ruby's Array() method for
-      # general array conversion.
+      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
+      # @raise [TypeError] if the value cannot be converted to an array
       #
-      # @param value [Object] value to coerce to array
-      # @param _options [Hash] coercion options (unused)
-      # @return [Array] coerced array value
-      # @raise [JSON::ParserError] if JSON parsing fails
+      # @example Converting a JSON string
+      #   Coercions::Array.call('["a", "b", "c"]') #=> ["a", "b", "c"]
       #
-      # @example
-      #   Coercions::Array.call("test")         # => ["test"]
-      #   Coercions::Array.call('["a","b"]')    # => ["a", "b"]
-      #   Coercions::Array.call([1, 2])         # => [1, 2]
+      # @example Converting other values
+      #   Coercions::Array.call("hello") #=> ["hello"]
+      #   Coercions::Array.call(123) #=> [123]
+      #   Coercions::Array.call(nil) #=> []
       def call(value, _options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)

data/lib/cmdx/coercions/big_decimal.rb

@@ -2,45 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to BigDecimal type.
+    # Coercion class for converting values to BigDecimal.
     #
-    # The BigDecimal coercion converts parameter values to BigDecimal objects
-    # for high-precision decimal arithmetic. Supports configurable precision
-    # and handles various numeric input formats.
-    #
-    # @example Basic BigDecimal coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :total_amount, type: :big_decimal
-    #     optional :tax_rate, type: :big_decimal, precision: 4
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::BigDecimal.call("123.45")          # => #<BigDecimal:...,'0.12345E3',18(27)>
-    #   Coercions::BigDecimal.call(42)                # => #<BigDecimal:...,'0.42E2',9(18)>
-    #   Coercions::BigDecimal.call("0.333333", precision: 6)  # Custom precision
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module BigDecimal
+    # This coercion handles conversion of various types to BigDecimal with
+    # configurable precision. It provides precise decimal arithmetic capabilities
+    # for financial calculations and other use cases requiring exact decimal representation.
+    class BigDecimal < Coercion
 
-      # Default precision for BigDecimal calculations
-      # @return [Integer] default precision value
       DEFAULT_PRECISION = 14
 
-      module_function
-
-      # Coerce a value to BigDecimal.
+      # Converts the given value to a BigDecimal.
+      #
+      # @param value [Object] the value to convert to a BigDecimal
+      # @param options [Hash] optional configuration
+      # @option options [Integer] :precision the precision for the BigDecimal (defaults to 14)
+      #
+      # @return [BigDecimal] the converted BigDecimal value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a BigDecimal
+      #
+      # @example Converting a string
+      #   Coercions::BigDecimal.call('123.45') #=> #<BigDecimal:...,'0.12345E3',18(27)>
       #
-      # @param value [Object] value to coerce to BigDecimal
-      # @param options [Hash] coercion options
-      # @option options [Integer] :precision decimal precision (default: 14)
-      # @return [BigDecimal] coerced BigDecimal value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with custom precision
+      #   Coercions::BigDecimal.call('123.456789', precision: 10) #=> #<BigDecimal:...,'0.123456789E3',18(27)>
       #
-      # @example
-      #   Coercions::BigDecimal.call("123.45")                    # => BigDecimal with default precision
-      #   Coercions::BigDecimal.call("0.333", precision: 10)      # => BigDecimal with custom precision
-      #   Coercions::BigDecimal.call(42.5)                        # => BigDecimal from float
+      # @example Converting an integer
+      #   Coercions::BigDecimal.call(100) #=> #<BigDecimal:...,'0.1E3',9(18)>
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError

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