domainic-attributer 0.1.0 → 0.2.0

data/sig/domainic/attributer/attribute/callback.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for managing change callbacks for an attribute.
+      # A class responsible for managing change callbacks for an attribute
       #
       # This class handles the execution of callbacks that are triggered when an
       # attribute's value changes. Each callback must be a Proc that accepts two
-      # arguments: the old value and the new value.
+      # arguments: the old value, and the new value
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Callback
@@ -16,26 +18,27 @@ module Domainic
 
         include BelongsToAttribute
 
-        # Initialize a new Callback instance.
+        # Initialize a new Callback instance
         #
-        # @param attribute [Attribute] the attribute this Callback belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Proc>] the handlers to use for processing
         #
-        # @return [Callback] the new instance of Callback
+        # @return [Callback] the new Callback instance
         def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
 
-        # Execute all callbacks for a value change.
+        # Execute all callbacks for a value change
         #
         # @param instance [Object] the instance on which to execute callbacks
         # @param old_value [Object] the previous value
         # @param new_value [Object] the new value
         #
+        # @raise [CallbackExecutionError] if any callback handlers raises an error
         # @return [void]
         def call: (untyped instance, untyped old_value, untyped new_value) -> void
 
         private
 
-        # Validate that a callback handler is a valid Proc.
+        # Validate that a callback handler is a valid Proc
         #
         # @param handler [Object] the handler to validate
         #

data/sig/domainic/attributer/attribute/coercer.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for coercing attribute values.
+      # A class responsible for coercing attribute values
       #
       # This class manages the coercion of values assigned to an attribute. Coercion can be
-      # handled by either a Proc that accepts a single value argument, or by referencing an
-      # instance method via Symbol.
+      # handled by either a {Proc} that accepts a single value argument, or by referencing an
+      # instance method via {Symbol}
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Coercer
@@ -18,25 +20,26 @@ module Domainic
 
         @handlers: Array[handler]
 
-        # Initialize a new Coercer instance.
+        # Initialize a new {Coercer} instance
         #
-        # @param attribute [Attribute] the attribute this Coercer belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Proc, Symbol>] the handlers to use for processing
         #
-        # @return [Coercer] the new instance of Coercer
+        # @return [Coercer] the new Coercer instance
         def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
 
-        # Process a value through all coercion handlers.
+        # Process a value through all coercion handlers
         #
         # @param instance [Object] the instance on which to perform coercion
         # @param value [Object] the value to coerce
         #
-        # @return [Object] the coerced value
-        def call: (untyped instance, untyped value) -> untyped
+        # @raise [CoercionExecutionError] if a coercion handler raises an error
+        # @return [Object, nil] the coerced value
+        def call: (untyped instance, untyped? value) -> untyped?
 
         private
 
-        # Process a value through a single coercion handler.
+        # Process a value through a single coercion handler
         #
         # @param instance [Object] the instance on which to perform coercion
         # @param handler [Proc, Symbol] the coercion handler
@@ -46,7 +49,7 @@ module Domainic
         # @return [Object] the coerced value
         def coerce_value: (untyped instance, handler, untyped value) -> untyped
 
-        # Validate that a coercion handler is valid.
+        # Validate that a coercion handler is valid
         #
         # @param handler [Object] the handler to validate
         #

data/sig/domainic/attributer/attribute/mixin/belongs_to_attribute.rbs

@@ -1,43 +1,45 @@
 module Domainic
   module Attributer
     class Attribute
-      # A mixin providing common functionality for classes that belong to an Attribute.
+      # A mixin providing common functionality for classes that belong to an Attribute
       #
       # This module provides initialization and duplication behavior for classes that are owned
       # by and work in conjunction with an Attribute instance. These classes typically handle
-      # specific aspects of attribute processing such as coercion, validation, or callbacks.
+      # specific aspects of attribute processing such as coercion, validation, or callbacks
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       module BelongsToAttribute
         @attribute: Attribute
 
-        # Initialize a new instance that belongs to an attribute.
+        # Initialize a new instance that belongs to an {Attribute}
         #
-        # @param attribute [Attribute] the attribute this instance belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         #
-        # @return [void]
+        # @return [BelongsToAttribute] the new BelongsToAttribute instance
         def initialize: (Attribute attribute, *untyped, **untyped) -> void
 
-        # Create a duplicate instance associated with a new attribute.
+        # Create a duplicate instance associated with a new {Attribute}
         #
         # @param new_attribute [Attribute] the new attribute to associate with
         #
-        # @return [BelongsToAttribute] a duplicate instance
+        # @return [BelongsToAttribute] duplicate instance with new {Attribute}
         def dup_with_attribute: (Attribute attribute) -> BelongsToAttribute
 
         private
 
-        # Generate a method name for error messages.
+        # Generate a method name for error messages
         #
-        # @return [String] the formatted method name
+        # @return [String] formatted method name
         def attribute_method_name: () -> String
 
-        # Ensure that an attribute is a valid {Attribute} instance.
+        # Ensure that an {Attribute} is a valid {Attribute} instance
         #
-        # @param attribute [Attribute] the attribute to validate
+        # @param attribute [Attribute] the {Attribute} to validate
         #
-        # @raise [TypeError] if the attribute is not a valid {Attribute} instance
+        # @raise [TypeError] if the attribute is not a valid Attribute instance
         # @return [void]
         def validate_attribute!: (Attribute attribute) -> void
       end

data/sig/domainic/attributer/attribute/signature.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for managing attribute signature information.
+      # A class responsible for managing attribute signature information
       #
-      # This class encapsulates the type and visibility configuration for an attribute.
+      # This class encapsulates the type and visibility configuration for an {Attribute}
       # It validates and manages whether an attribute is an argument or option, as well
-      # as controlling read and write visibility (public, protected, or private).
+      # as controlling read and write visibility (public, protected, or private)
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Signature
@@ -20,10 +22,10 @@ module Domainic
 
         include BelongsToAttribute
 
-        # @return [Hash{Symbol => Object}] Default options for a new Signature instance.
+        # @return [Hash{Symbol => Object}] Default options for a new Signature instance
         DEFAULT_OPTIONS: default_options
 
-        # Constants defining valid attribute types.
+        # Constants defining valid attribute types
         #
         # @author {https://aaronmallen.me Aaron Allen}
         # @since 0.1.0
@@ -38,7 +40,7 @@ module Domainic
           ALL: Array[type_symbol]
         end
 
-        # Constants defining valid visibility levels.
+        # Constants defining valid visibility levels
         #
         # @author {https://aaronmallen.me Aaron Allen}
         # @since 0.1.0
@@ -68,110 +70,119 @@ module Domainic
 
         @type: type_symbol
 
+        # Get the position of the attribute
+        #
         # @return [Integer, nil] the position of the attribute
         attr_reader position: Integer?
 
+        # Get the visibility level for reading the attribute
+        #
         # @return [Symbol] the visibility level for reading the attribute
         attr_reader read_visibility: visibility_symbol
 
+        # Get the attribute type
+        #
         # @return [Symbol] the type of the attribute
         attr_reader type: type_symbol
 
+        # Get the visibility level for writing the attribute
+        #
         # @return [Symbol] the visibility level for writing the attribute
         attr_reader write_visibility: visibility_symbol
 
-        # Initialize a new Signature instance.
+        # Initialize a new {Signature} instance
         #
-        # @param attribute [Attribute] the attribute this signature belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param options [Hash{Symbol => Object}] the signature options
-        # @option options [Boolean] nilable (true) whether the attribute is allowed to be nil.
+        # @option options [Boolean] nilable (true) whether the attribute is allowed to be nil
         # @option options [Integer, nil] position (nil) optional position for ordered attributes
         # @option options [Symbol] read (:public) the read visibility
         # @option options [Boolean] required (false) whether the attribute is required
         # @option options [Symbol] type the type of attribute
         # @option options [Symbol] write (:public) the write visibility
         #
-        # @return [void]
+        # @raise [ArgumentError] if the configuration is invalid
+        # @return [Signature] the new Signature instance
         def initialize: (Attribute attribute, type: type_symbol, ?nilable: bool, ?position: Integer?, ?read: visibility_symbol, ?required: bool, ?write: visibility_symbol) -> void
 
-        # Check if this signature is for an argument attribute.
+        # Check if this signature is for an argument attribute
         #
         # @return [Boolean] true if this is an argument attribute
         def argument?: () -> bool
 
-        # Check if the attribute is allowed to be nil.
+        # Check if the attribute allows nil values
         #
-        # @return [Boolean] true if the attribute is allowed to be nil
+        # @return [Boolean] true if the attribute allows nil values
         def nilable?: () -> bool
 
-        # Check if this signature is for an option attribute.
+        # Check if this signature is for an option attribute
         #
         # @return [Boolean] true if this is an option attribute
         def option?: () -> bool
 
-        # Check if this signature is for an optional attribute.
+        # Check if this signature is for an optional attribute
         #
         # @return [Boolean] true if this is an optional attribute
         def optional?: () -> bool
 
-        # Check if both read and write operations are private.
+        # Check if both read and write operations are private
         #
         # @return [Boolean] true if both read and write are private
         def private?: () -> bool
 
-        # Check if read operations are private.
+        # Check if read operations are private
         #
         # @return [Boolean] true if read operations are private
         def private_read?: () -> bool
 
-        # Check if write operations are private.
+        # Check if write operations are private
         #
         # @return [Boolean] true if write operations are private
         def private_write?: () -> bool
 
-        # Check if both read and write operations are protected.
+        # Check if both read and write operations are protected
         #
         # @return [Boolean] true if both read and write are protected
         def protected?: () -> bool
 
-        # Check if read operations are protected.
+        # Check if read operations are protected
         #
         # @return [Boolean] true if read operations are protected
         def protected_read?: () -> bool
 
-        # Check if write operations are protected.
+        # Check if write operations are protected
         #
         # @return [Boolean] true if write operations are protected
         def protected_write?: () -> bool
 
-        # Check if both read and write operations are public.
+        # Check if both read and write operations are public
         #
         # @return [Boolean] true if both read and write are public
         def public?: () -> bool
 
-        # Check if read operations are public.
+        # Check if read operations are public
         #
         # @return [Boolean] true if read operations are public
         def public_read?: () -> bool
 
-        # Check if write operations are public.
+        # Check if write operations are public
         #
         # @return [Boolean] true if write operations are public
         def public_write?: () -> bool
 
-        # Check if the attribute is required.
+        # Check if this signature requires an attribute value
         #
-        # @return [Boolean] true if the attribute is required
+        # @return [Boolean] true if this signature requires an attribute value
         def required?: () -> bool
 
         private
 
-        # Get signature options as a hash.
+        # Get signature options as a hash
         #
         # @return [Hash] the signature options
         def to_options: () -> initialize_options
 
-        # Validate that a value is a Boolean.
+        # Validate that a value is a boolean
         #
         # @param name [String, Symbol] the name of the attribute being validated
         # @param value [Boolean] the value to validate
@@ -180,7 +191,7 @@ module Domainic
         # @return [void]
         def validate_boolean!: (String | Symbol name, bool value) -> void
 
-        # Validate all initialization options.
+        # Validate all initialization options
         #
         # @param options [Hash{Symbol => Object}] the options to validate
         # @option options [Boolean] nilable the nilable flag to validate
@@ -193,7 +204,7 @@ module Domainic
         # @return [void]
         def validate_initialize_options!: (Hash[Symbol, untyped] options) -> void
 
-        # Validate that a position value is valid.
+        # Validate that a position value is valid
         #
         # @param position [Integer, nil] the position to validate
         #
@@ -201,7 +212,7 @@ module Domainic
         # @return [void]
         def validate_position!: (Integer? position) -> void
 
-        # Validate that a type value is valid.
+        # Validate that a type value is valid
         #
         # @param type [Symbol] the type to validate
         #
@@ -209,7 +220,7 @@ module Domainic
         # @return [void]
         def validate_type!: (type_symbol type) -> void
 
-        # Validate that visibility values are valid.
+        # Validate that visibility values are valid
         #
         # @param type [Symbol] which visibility setting to validate
         # @param value [Symbol] the visibility value to validate

data/sig/domainic/attributer/attribute/validator.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for validating attribute values.
+      # A class responsible for validating attribute values
       #
       # This class manages the validation of values assigned to an attribute. Validation
-      # can be performed either by a Proc that accepts a single value argument and returns
-      # a boolean, or by any object that responds to the `===` operator.
+      # can be performed either by a {Proc} that accepts a single value argument and returns
+      # a boolean, or by any object that responds to the `===` operator
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Validator
@@ -32,38 +34,49 @@ module Domainic
 
         @handlers: Array[handler]
 
-        # Initialize a new Validator instance.
+        # Initialize a new Validator instance
         #
-        # @param attribute [Attribute] the attribute this Validator belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Class, Module, Object, Proc>] the handlers to use for processing
         #
-        # @return [Validator] the new instance of Validator
+        # @return [Validator] the new Validator instance
         def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
 
-        # Validate a value using all configured validators.
+        # Validate a value using all configured validators
         #
         # @param instance [Object] the instance on which to perform validation
         # @param value [Object] the value to validate
         #
         # @raise [ArgumentError] if the value fails validation
+        # @raise [ValidationExecutionError] if errors occur during validation execution
         # @return [void]
         def call: (untyped instance, untyped value) -> void
 
         private
 
-        # Handle a `nil` value.
+        # Handle a nil value
         #
         # @raise [ArgumentError] if the attribute is not nilable
-        # @return [true] if the attribute is nilable
+        # @return [Boolean] true if the attribute is nilable
         def handle_nil!: () -> bool
 
-        # Handle an {Undefined} value.
+        # Handle an {Undefined} value
         #
         # @raise [ArgumentError] if the attribute is required
-        # @return [true] if the attribute is optional
+        # @return [Boolean] true if the attribute is optional
         def handle_undefined!: () -> bool
 
-        # Validate that a validation handler is valid.
+        # Run all configured validations
+        #
+        # @param instance [Object] the instance on which to perform validation
+        # @param value [Object] the value to validate
+        #
+        # @raise [ArgumentError] if the value fails validation
+        # @raise [ValidationExecutionError] if errors occur during validation execution
+        # @return [void]
+        def run_validations!: (untyped instance, untyped value) -> void
+
+        # Validate that a validation handler is valid
         #
         # @param handler [Object] the handler to validate
         #
@@ -71,11 +84,13 @@ module Domainic
         # @return [void]
         def validate_handler!: (handler handler) -> void
 
-        # Validate a value using a single handler.
+        # Validate a value using a single handler
         #
         # @param handler [Object] the handler to use for validation
         # @param instance [Object] the instance on which to perform validation
         # @param value [Object] the value to validate
+        #
+        # @return [Boolean] true if validation succeeds
         def validate_value!: (handler handler, untyped instance, untyped value) -> bool
       end
     end

data/sig/domainic/attributer/attribute.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
-    # A class representing a managed attribute in the Domainic::Attributer system.
+    # A class representing a managed attribute in the {Domainic::Attributer} system
     #
     # This class serves as the core component of the attribute management system.
     # It coordinates type information, visibility settings, value coercion,
     # validation, and change notifications for an attribute. Each instance
-    # represents a single attribute definition within a class.
+    # represents a single attribute definition within a class
     #
+    # @api private
+    # @!visibility private
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     class Attribute
@@ -28,22 +30,30 @@ module Domainic
 
       @base: __todo__
 
+      # Get the class or module this attribute belongs to
+      #
       # @return [Class, Module] the class or module this attribute belongs to
       attr_reader base: __todo__
 
+      # Get the description of the attribute
+      #
       # @return [String, nil] the description of the attribute
       attr_reader description: String?
 
+      # Get the name of the attribute
+      #
       # @return [Symbol] the name of the attribute
       attr_reader name: Symbol
 
+      # Get the signature configuration for this attribute
+      #
       # @return [Signature] the signature configuration for this attribute
       attr_reader signature: Signature
 
-      # Initialize a new Attribute instance.
+      # Initialize a new {Attribute} instance
       #
       # @param base [Class, Module] the class or module this attribute belongs to
-      # @param options [Hash] the options to create the attribute with
+      # @param options [Hash{Symbol => Object}] the options to create the attribute with
       # @option options [Array<Proc>, Proc] :callbacks callbacks to trigger on value changes
       # @option options [Array<Proc, Symbol>, Proc, Symbol] :coercers handlers for value coercion
       # @option options [Object] :default the default value or generator
@@ -58,11 +68,10 @@ module Domainic
       # @option options [Symbol] :write the write visibility
       #
       # @raise [ArgumentError] if the configuration is invalid
-      # @return [void]
-      #
+      # @return [Attribute] the new Attribute instance
       def initialize: (__todo__ base, name: String | Symbol, type: Signature::type_symbol, ?callbacks: Array[Callback::handler] | Callback::handler, ?coercers: Array[Coercer::handler] | Coercer::handler, ?default: untyped, ?description: String?, ?nilable: bool, ?position: Integer?, ?read: Signature::visibility_symbol, ?required: bool, ?validators: Array[Validator::handler] | Validator::handler, ?write: Signature::visibility_symbol) -> void
 
-      # Apply a value to the attribute on an instance.
+      # Apply a value to the attribute on an instance
       #
       # This method applies all attribute constraints (coercion, validation) to a value
       # and sets it on the given instance. It manages the complete lifecycle of setting
@@ -80,36 +89,37 @@ module Domainic
       # @return [void]
       def apply!: (untyped instance, untyped value) -> void
 
-      # Check if this attribute has a default value.
+      # Check if this attribute has a default value
       #
       # @return [Boolean] true if a default value is set
       def default?: () -> bool
 
-      # Create a duplicate instance for a new base class.
+      # Create a duplicate instance for a new base class
       #
       # @param new_base [Class, Module] the new base class
       #
+      # @raise [ArgumentError] if the new base is invalid
       # @return [Attribute] the duplicated instance
       def dup_with_base: (__todo__ new_base) -> Attribute
 
-      # Generate the default value for this attribute.
+      # Generate the default value for this attribute
       #
       # @param instance [Object] the instance to generate the default for
       #
       # @return [Object] the generated default value
       def generate_default: (untyped instance) -> untyped
 
-      # Merge this attribute's configuration with another.
+      # Merge this attribute's configuration with another
       #
       # @param other [Attribute] the attribute to merge with
       #
-      # @raise [ArgumentError] if other is not an Attribute
+      # @raise [ArgumentError] if other is not an {Attribute}
       # @return [Attribute] a new attribute with merged configuration
       def merge: (Attribute other) -> Attribute
 
       private
 
-      # Apply initialization options to create attribute components.
+      # Apply initialization options to create attribute components
       #
       # @param base [Class, Module] the base class
       # @param options [Hash] the initialization options
@@ -117,19 +127,19 @@ module Domainic
       # @return [void]
       def apply_initialize_options!: (__todo__ base, initialize_options options) -> void
 
-      # Initialize a copy of this attribute.
+      # Initialize a copy of this attribute
       #
       # @param source [Attribute] the source attribute
       #
       # @return [Attribute] the initialized copy
       def initialize_copy: ...
 
-      # Get this attribute's configuration as options.
+      # Get this attribute's configuration as options
       #
       # @return [Hash] the configuration options
       def to_options: () -> initialize_options
 
-      # Validate and apply initialization options.
+      # Validate and apply initialization options
       #
       # @param base [Class, Module] the base class
       # @param options [Hash] the initialization options
@@ -137,7 +147,7 @@ module Domainic
       # @return [void]
       def validate_and_apply_initialize_options!: (__todo__ base, initialize_options options) -> void
 
-      # Validate initialization options.
+      # Validate initialization options
       #
       # @param base [Class, Module] the base class
       # @param options [Hash] the initialization options