cmdx 1.1.0 → 1.1.1

data/lib/cmdx/parameter.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter definition system for CMDx tasks.
+  # Parameter definition and management for task attribute configuration.
   #
-  # This class manages parameter definitions including type coercion, validation,
-  # and nested parameter structures. It handles the creation of accessor methods
-  # on task classes and provides a flexible system for defining required and
-  # optional parameters with various data types and validation rules.
+  # Parameter provides a flexible system for defining, validating, and managing
+  # task parameters with support for type coercion, nested parameter structures,
+  # validation rules, and dynamic attribute generation. Parameters can be defined
+  # as required or optional with various configuration options including custom
+  # naming, source specification, and child parameter definitions.
   class Parameter
 
     cmdx_attr_delegator :invalid?, :valid?,
@@ -36,22 +37,31 @@ module CMDx
     # @return [CMDx::Errors] Validation errors for this parameter
     attr_reader :errors
 
-    # Creates a new parameter definition with the given name and options.
+    # Creates a new parameter definition with the specified configuration.
     #
-    # @param name [Symbol] The parameter name
-    # @param options [Hash] Configuration options for the parameter
-    # @option options [Class] :klass The task class this parameter belongs to (required)
-    # @option options [Parameter] :parent The parent parameter for nested parameters
-    # @option options [Symbol, Array<Symbol>] :type (:virtual) The parameter type(s) for coercion
-    # @option options [Boolean] :required (false) Whether the parameter is required
-    # @param block [Proc] Optional block for defining nested parameters
-    # @return [Parameter] The newly created parameter
-    # @raise [KeyError] If the :klass option is not provided
+    # @param name [Symbol, String] the parameter name
+    # @param options [Hash] parameter configuration options
+    # @option options [Class] :klass the task class this parameter belongs to (required)
+    # @option options [Parameter] :parent the parent parameter for nested definitions
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Boolean] :required whether the parameter is required for task execution
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name for the parameter
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @example Create a simple parameter
-    #   Parameter.new(:name, klass: MyTask, type: :string, required: true)
+    # @return [Parameter] a new parameter instance
     #
-    # @example Create a parameter with nested children
+    # @raise [KeyError] if the :klass option is not provided
+    #
+    # @example Create a simple required parameter
+    #   Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
+    #
+    # @example Create parameter with validation
+    #   Parameter.new(:email, klass: MyTask, type: :string, validates: { format: /@/ })
+    #
+    # @example Create nested parameter with children
     #   Parameter.new(:user, klass: MyTask, type: :hash) do
     #     required :name, type: :string
     #     optional :age, type: :integer
@@ -73,21 +83,32 @@ module CMDx
 
     class << self
 
-      # Creates one or more optional parameters with the given names and options.
+      # Creates one or more optional parameter definitions.
+      #
+      # @param names [Array<Symbol>] parameter names to define as optional
+      # @param options [Hash] parameter configuration options
+      # @option options [Class] :klass the task class this parameter belongs to
+      # @option options [Parameter] :parent the parent parameter for nested definitions
+      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+      # @option options [Symbol] :source the source context for parameter resolution
+      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+      # @option options [Hash] :validates validation rules to apply to the parameter
+      # @option options [Object] :default default value when parameter is not provided
+      # @param block [Proc] optional block for defining nested parameters
       #
-      # @param names [Array<Symbol>] Parameter names to create
-      # @param options [Hash] Configuration options for all parameters
-      # @param block [Proc] Optional block for defining nested parameters
-      # @return [Array<Parameter>] The created optional parameters
-      # @raise [ArgumentError] If no parameters are given or :as option is used with multiple names
+      # @return [Array<Parameter>] array of created optional parameter instances
       #
-      # @example Create multiple optional parameters
-      #   Parameter.optional(:name, :email, type: :string, klass: MyTask)
+      # @raise [ArgumentError] if no parameter names are provided
+      # @raise [ArgumentError] if :as option is used with multiple parameter names
       #
-      # @example Create optional parameter with nested structure
-      #   Parameter.optional(:user, klass: MyTask, type: :hash) do
-      #     required :name, type: :string
-      #   end
+      # @example Define single optional parameter
+      #   Parameter.optional(:description, klass: MyTask, type: :string)
+      #
+      # @example Define multiple optional parameters
+      #   Parameter.optional(:name, :email, klass: MyTask, type: :string)
+      #
+      # @example Define optional parameter with custom name
+      #   Parameter.optional(:user_id, klass: MyTask, type: :integer, as: :current_user_id)
       def optional(*names, **options, &)
         if names.none?
           raise ArgumentError, "no parameters given"
@@ -98,133 +119,174 @@ module CMDx
         names.filter_map { |n| new(n, **options, &) }
       end
 
-      # Creates one or more required parameters with the given names and options.
+      # Creates one or more required parameter definitions.
+      #
+      # @param names [Array<Symbol>] parameter names to define as required
+      # @param options [Hash] parameter configuration options
+      # @option options [Class] :klass the task class this parameter belongs to
+      # @option options [Parameter] :parent the parent parameter for nested definitions
+      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+      # @option options [Symbol] :source the source context for parameter resolution
+      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+      # @option options [Hash] :validates validation rules to apply to the parameter
+      # @option options [Object] :default default value when parameter is not provided
+      # @param block [Proc] optional block for defining nested parameters
+      #
+      # @return [Array<Parameter>] array of created required parameter instances
       #
-      # @param names [Array<Symbol>] Parameter names to create
-      # @param options [Hash] Configuration options for all parameters
-      # @param block [Proc] Optional block for defining nested parameters
-      # @return [Array<Parameter>] The created required parameters
-      # @raise [ArgumentError] If no parameters are given or :as option is used with multiple names
+      # @raise [ArgumentError] if no parameter names are provided
+      # @raise [ArgumentError] if :as option is used with multiple parameter names
       #
-      # @example Create multiple required parameters
-      #   Parameter.required(:name, :email, type: :string, klass: MyTask)
+      # @example Define single required parameter
+      #   Parameter.required(:user_id, klass: MyTask, type: :integer)
       #
-      # @example Create required parameter with validation
-      #   Parameter.required(:age, type: :integer, validate: { numeric: { greater_than: 0 } }, klass: MyTask)
+      # @example Define multiple required parameters
+      #   Parameter.required(:name, :email, klass: MyTask, type: :string)
+      #
+      # @example Define required parameter with validation
+      #   Parameter.required(:email, klass: MyTask, type: :string, validates: { format: /@/ })
       def required(*names, **options, &)
         optional(*names, **options.merge(required: true), &)
       end
 
     end
 
-    # Creates one or more optional child parameters under this parameter.
+    # Defines optional child parameters for nested parameter structures.
     #
-    # @param names [Array<Symbol>] Parameter names to create
-    # @param options [Hash] Configuration options for all parameters
-    # @param block [Proc] Optional block for defining nested parameters
-    # @return [Array<Parameter>] The created optional child parameters
+    # @param names [Array<Symbol>] parameter names to define as optional children
+    # @param options [Hash] parameter configuration options
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @example Add optional child parameters
-    #   user_param.optional(:nickname, :bio, type: :string)
+    # @return [Array<Parameter>] array of created optional child parameter instances
     #
-    # @example Add optional child with further nesting
-    #   user_param.optional(:preferences, type: :hash) do
-    #     required :theme, type: :string
-    #   end
+    # @raise [ArgumentError] if no parameter names are provided
+    # @raise [ArgumentError] if :as option is used with multiple parameter names
+    #
+    # @example Define optional child parameters
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
+    #   user_param.optional(:description, :bio, type: :string)
     def optional(*names, **options, &)
       parameters = Parameter.optional(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
-    # Creates one or more required child parameters under this parameter.
+    # Defines required child parameters for nested parameter structures.
+    #
+    # @param names [Array<Symbol>] parameter names to define as required children
+    # @param options [Hash] parameter configuration options
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @param names [Array<Symbol>] Parameter names to create
-    # @param options [Hash] Configuration options for all parameters
-    # @param block [Proc] Optional block for defining nested parameters
-    # @return [Array<Parameter>] The created required child parameters
+    # @return [Array<Parameter>] array of created required child parameter instances
     #
-    # @example Add required child parameters
-    #   user_param.required(:first_name, :last_name, type: :string)
+    # @raise [ArgumentError] if no parameter names are provided
+    # @raise [ArgumentError] if :as option is used with multiple parameter names
     #
-    # @example Add required child with validation
-    #   user_param.required(:email, type: :string, validate: { format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i } })
+    # @example Define required child parameters
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
+    #   user_param.required(:name, :email, type: :string)
     def required(*names, **options, &)
       parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
-    # Checks if this parameter is required.
+    # Checks if the parameter is marked as required for task execution.
     #
-    # @return [Boolean] True if the parameter is required, false otherwise
+    # @return [Boolean] true if the parameter is required, false otherwise
     #
     # @example Check if parameter is required
-    #   param.required? # => true
+    #   param = Parameter.new(:name, klass: MyTask, required: true)
+    #   param.required? #=> true
     def required?
       !!@required
     end
 
-    # Checks if this parameter is optional.
+    # Checks if the parameter is marked as optional for task execution.
     #
-    # @return [Boolean] True if the parameter is optional, false otherwise
+    # @return [Boolean] true if the parameter is optional, false otherwise
     #
     # @example Check if parameter is optional
-    #   param.optional? # => false
+    #   param = Parameter.new(:description, klass: MyTask, required: false)
+    #   param.optional? #=> true
     def optional?
       !required?
     end
 
-    # Gets the method name that will be used to access this parameter's value.
+    # Generates the method name that will be created on the task class for this parameter.
     #
-    # @return [Symbol] The method name for accessing this parameter
+    # @return [Symbol] the method name with any configured prefix, suffix, or custom naming
     #
-    # @example Get method name
-    #   param.method_name # => :user_name
+    # @example Get method name for simple parameter
+    #   param = Parameter.new(:user_id, klass: MyTask)
+    #   param.method_name #=> :user_id
+    #
+    # @example Get method name with custom naming
+    #   param = Parameter.new(:user_id, klass: MyTask, as: :current_user_id)
+    #   param.method_name #=> :current_user_id
     def method_name
       @method_name ||= Utils::NameAffix.call(name, method_source, options)
     end
 
-    # Gets the source object from which this parameter's value will be retrieved.
+    # Determines the source context for parameter resolution and method name generation.
+    #
+    # @return [Symbol] the source identifier used for parameter resolution
     #
-    # @return [Symbol] The method source (:context by default, or parent's method_name)
+    # @example Get method source for simple parameter
+    #   param = Parameter.new(:user_id, klass: MyTask)
+    #   param.method_source #=> :context
     #
-    # @example Get method source
-    #   param.method_source # => :context
+    # @example Get method source for nested parameter
+    #   parent = Parameter.new(:user, klass: MyTask)
+    #   child = Parameter.new(:name, klass: MyTask, parent: parent)
+    #   child.method_source #=> :user
     def method_source
       @method_source ||= options[:source] || parent&.method_name || :context
     end
 
-    # Converts the parameter to a hash representation.
+    # Converts the parameter to a hash representation for serialization.
     #
-    # @return [Hash] A hash representation of the parameter
+    # @return [Hash] hash containing all parameter metadata and configuration
     #
-    # @example Convert to hash
-    #   param.to_h # => { name: :user_name, type: :string, required: true, ... }
+    # @example Convert parameter to hash
+    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
+    #   param.to_h
+    #   #=> { name: :user_id, type: :integer, required: true, ... }
     def to_h
       ParameterSerializer.call(self)
     end
 
-    # Converts the parameter to a string representation.
+    # Converts the parameter to a formatted string representation for inspection.
     #
-    # @return [String] A string representation of the parameter
+    # @return [String] human-readable string representation of the parameter
     #
-    # @example Convert to string
-    #   param.to_s # => "Parameter(name: user_name, type: string, required: true)"
+    # @example Convert parameter to string
+    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
+    #   param.to_s
+    #   #=> "Parameter: name=user_id type=integer required=true ..."
     def to_s
       ParameterInspector.call(to_h)
     end
 
     private
 
-    # Defines the attribute accessor method for this parameter on the task class.
-    # The method handles parameter value retrieval, coercion, and validation.
+    # Dynamically defines a method on the task class for parameter value access.
+    #
+    # @param parameter [Parameter] the parameter to create a method for
     #
-    # @param parameter [Parameter] The parameter to define the method for
     # @return [void]
-    # @raise [CoercionError] If parameter value cannot be coerced to the expected type
-    # @raise [ValidationError] If parameter value fails validation
     #
-    # @example Define parameter method (internal use)
-    #   define_attribute(param) # Defines a private method on the task class
+    # @example Define parameter method on task class
+    #   # Creates a private method that evaluates and caches parameter values
+    #   # with automatic error handling for coercion and validation failures
     def define_attribute(parameter)
       klass.send(:define_method, parameter.method_name) do
         @cmd_parameter_value_cache ||= {}

data/lib/cmdx/parameter_inspector.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter inspection and formatting utilities for readable parameter representation.
+  # Provides formatted inspection and display functionality for parameter objects.
   #
-  # This module provides functionality to format parameter metadata into human-readable
-  # strings for debugging, logging, and introspection purposes. It handles nested
-  # parameter structures with proper indentation and displays essential parameter
-  # information in a structured format.
+  # This module formats parameter information into human-readable string representations,
+  # including nested parameter structures with proper indentation. It processes parameter
+  # hashes in a consistent order and handles child parameter relationships for complex
+  # parameter hierarchies.
   module ParameterInspector
 
     ORDERED_KEYS = %i[
@@ -15,30 +15,43 @@ module CMDx
 
     module_function
 
-    # Formats a parameter hash into a human-readable string representation.
+    # Formats a parameter hash into a human-readable inspection string.
     #
-    # This method converts parameter metadata into a structured string format
-    # that displays key parameter information in a consistent order. For parameters
-    # with nested children, it recursively formats child parameters with proper
-    # indentation to show the hierarchical structure.
+    # Creates a formatted string representation of parameter information,
+    # displaying attributes in a consistent order with proper indentation
+    # for nested child parameters. The method recursively processes child
+    # parameters with increased indentation depth for visual hierarchy.
     #
     # @param parameter [Hash] the parameter hash to format
-    # @param depth [Integer] the current nesting depth for indentation (default: 1)
+    # @option parameter [Symbol, String] :name the parameter name
+    # @option parameter [Symbol, Array<Symbol>] :type the parameter type(s)
+    # @option parameter [Symbol] :source the parameter source context
+    # @option parameter [Boolean] :required whether the parameter is required
+    # @option parameter [Hash] :options additional parameter configuration options
+    # @option parameter [Array<Hash>] :children nested child parameter definitions
+    # @param depth [Integer] the indentation depth for nested parameters (defaults to 1)
     #
-    # @return [String] a formatted string representation of the parameter
+    # @return [String] formatted multi-line string representation of the parameter
     #
-    # @example Format a parameter with nested children
-    #   param = {
-    #     name: :user, type: :hash, source: :context, required: false, options: {},
+    # @example Format a simple parameter
+    #   parameter = { name: :user_id, type: :integer, required: true }
+    #   ParameterInspector.call(parameter)
+    #   #=> "Parameter: name=user_id type=integer required=true"
+    #
+    # @example Format a parameter with children
+    #   parameter = {
+    #     name: :payment,
+    #     type: :hash,
+    #     required: true,
     #     children: [
-    #       { name: :name, type: :string, source: :user, required: true, options: {}, children: [] },
-    #       { name: :age, type: :integer, source: :user, required: false, options: {}, children: [] }
+    #       { name: :amount, type: :big_decimal, required: true },
+    #       { name: :currency, type: :string, required: true }
     #     ]
     #   }
-    #   ParameterInspector.call(param)
-    #   # => "Parameter: name=user type=hash source=context required=false options={}
-    #   #      ↳ Parameter: name=name type=string source=user required=true options={}
-    #   #      ↳ Parameter: name=age type=integer source=user required=false options={}"
+    #   ParameterInspector.call(parameter)
+    #   #=> "Parameter: name=payment type=hash required=true
+    #   #       ↳ Parameter: name=amount type=big_decimal required=true
+    #   #       ↳ Parameter: name=currency type=string required=true"
     def call(parameter, depth = 1)
       ORDERED_KEYS.filter_map do |key|
         value = parameter[key]

data/lib/cmdx/parameter_registry.rb

@@ -1,34 +1,39 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing parameter definitions and validation within tasks.
+  # Registry for managing parameter definitions within tasks.
   #
-  # This registry handles the storage and validation of parameter definitions,
-  # including nested parameter structures and recursive validation logic.
+  # This registry maintains a collection of parameter definitions and provides
+  # validation functionality to ensure all parameters are properly configured
+  # and accessible on their associated tasks. It supports both flat and nested
+  # parameter structures through recursive validation.
   class ParameterRegistry
 
-    # The internal array storing parameter definitions.
-    #
-    # @return [Array] array containing parameter definition objects
+    # @return [Array<Parameter>] array containing parameter definition objects
     attr_reader :registry
 
-    # Initializes a new parameter registry.
+    # Initializes a new parameter registry with an empty parameter collection.
     #
     # @return [ParameterRegistry] a new parameter registry instance
     #
-    # @example Creating an empty registry
-    #   ParameterRegistry.new
+    # @example Creating a new registry
+    #   registry = ParameterRegistry.new
+    #   registry.registry #=> []
     def initialize
       @registry = []
     end
 
-    # Creates a deep copy of the parameter registry.
+    # Creates a duplicate of the parameter registry with deep-copied parameters.
+    #
+    # This method creates a new registry instance with duplicated parameter
+    # definitions, ensuring changes to the duplicate don't affect the original.
     #
     # @return [ParameterRegistry] a new registry instance with duplicated parameters
     #
-    # @example Duplicating a registry
+    # @example Duplicate a registry
     #   original = ParameterRegistry.new
-    #   copy = original.dup
+    #   duplicate = original.dup
+    #   duplicate.object_id != original.object_id #=> true
     def dup
       new_registry = self.class.new
       new_registry.instance_variable_set(:@registry, registry.map(&:dup))
@@ -39,43 +44,45 @@ module CMDx
     #
     # @return [Boolean] true if all parameters are valid, false otherwise
     #
-    # @example Checking registry validity
-    #   registry.valid?
-    #   # => true
+    # @example Check registry validity
+    #   registry.valid? #=> true
     def valid?
       registry.all?(&:valid?)
     end
 
     # Validates all parameters in the registry against a task instance.
     #
+    # This method ensures that each parameter is properly defined and accessible
+    # on the provided task, including nested parameters through recursive validation.
+    #
     # @param task [Task] the task instance to validate parameters against
     #
     # @return [void]
     #
-    # @example Validating parameters
-    #   registry.validate!(task)
+    # @raise [NoMethodError] if a parameter method is not defined on the task
+    #
+    # @example Validate parameters against a task
+    #   registry.validate!(task_instance)
     def validate!(task)
       registry.each { |p| recursive_validate!(task, p) }
     end
 
-    # Returns a hash representation of the registry.
+    # Converts the parameter registry to a hash representation.
     #
-    # @return [Hash] serialized hash representation of all parameters
+    # @return [Array<Hash>] array of parameter hash representations
     #
-    # @example Getting registry hash
-    #   registry.to_h
-    #   # => { name: { type: :string, required: true }, age: { type: :integer } }
+    # @example Convert registry to hash
+    #   registry.to_h #=> [{name: :user_id, type: :integer}, {name: :email, type: :string}]
     def to_h
       registry.map(&:to_h)
     end
 
-    # Returns a string representation of the registry.
+    # Converts the parameter registry to a string representation.
     #
-    # @return [String] formatted string representation of all parameters
+    # @return [String] string representation of all parameters, joined by newlines
     #
-    # @example Getting registry string
-    #   registry.to_s
-    #   # => "name (string, required), age (integer)"
+    # @example Convert registry to string
+    #   registry.to_s #=> "user_id: integer\nemail: string"
     def to_s
       registry.map(&:to_s).join("\n")
     end
@@ -84,13 +91,12 @@ module CMDx
 
     # Recursively validates a parameter and its children against a task.
     #
-    # @param task [Task] the task instance to validate against
+    # @param task [Task] the task instance to validate the parameter against
     # @param parameter [Parameter] the parameter to validate
     #
     # @return [void]
     #
-    # @example Recursive validation (internal use)
-    #   recursive_validate!(task, parameter)
+    # @raise [NoMethodError] if the parameter method is not defined on the task
     def recursive_validate!(task, parameter)
       task.send(parameter.method_name) # Make sure parameter is defined on task
       parameter.children.each { |child| recursive_validate!(task, child) }

data/lib/cmdx/parameter_serializer.rb

@@ -1,32 +1,39 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter serialization module for converting parameter objects to hash format.
+  # Parameter serialization utilities for converting parameter objects to hash representations.
   #
-  # This module provides functionality to serialize parameter objects into a
-  # standardized hash representation that includes essential metadata about
-  # the parameter such as its source, name, type, required status, options,
-  # and child parameters. The serialized format is commonly used for debugging,
-  # logging, and introspection purposes.
+  # ParameterSerializer provides functionality to convert parameter definition objects
+  # into structured hash format for serialization, introspection, and data exchange.
+  # It extracts essential parameter metadata including source context, method names,
+  # type information, requirement status, options, and nested child parameters.
   module ParameterSerializer
 
     module_function
 
-    # Serializes a parameter object into a hash representation.
+    # Converts a parameter object into a hash representation for serialization.
     #
-    # @param parameter [Parameter] the parameter object to serialize
+    # This method extracts key metadata from a parameter definition and structures
+    # it into a hash format suitable for serialization, storage, or transmission.
+    # Child parameters are recursively serialized to maintain nested structure.
     #
-    # @return [Hash] a hash containing the parameter's metadata
+    # @param parameter [CMDx::Parameter] the parameter object to serialize
     #
-    # @raise [NoMethodError] if the parameter doesn't respond to required methods
+    # @return [Hash] a hash containing the parameter's metadata and configuration
+    # @option return [Symbol] :source the source context for parameter resolution
+    # @option return [Symbol] :name the method name generated for this parameter
+    # @option return [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option return [Boolean] :required whether the parameter is required for execution
+    # @option return [Hash] :options the parameter configuration options
+    # @option return [Array<Hash>] :children serialized child parameters for nested structures
     #
-    # @example Serialize a parameter with nested children
-    #   param = Parameter.new(:user, klass: MyTask, type: :hash) do
+    # @example Serialize a nested parameter with children
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash) do
     #     required :name, type: :string
     #     optional :age, type: :integer
     #   end
-    #   ParameterSerializer.call(param)
-    #   # => {
+    #   ParameterSerializer.call(user_param)
+    #   #=> {
     #   #   source: :context,
     #   #   name: :user,
     #   #   type: :hash,