domainic-attributer 0.1.0 → 0.2.0

data/lib/domainic/attributer/attribute.rb

@@ -8,13 +8,15 @@ require 'domainic/attributer/undefined'
 
 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
@@ -43,22 +45,30 @@ module Domainic
       # @rbs @signature: Signature
       # @rbs @validator: Validator
 
+      # 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
@@ -73,8 +83,7 @@ module Domainic
       # @option options [Symbol] :write the write visibility
       #
       # @raise [ArgumentError] if the configuration is invalid
-      # @return [void]
-      #
+      # @return [Attribute] the new Attribute instance
       # @rbs (
       #   __todo__ base,
       #   ?callbacks: Array[Callback::handler] | Callback::handler,
@@ -98,7 +107,7 @@ module Domainic
         raise ArgumentError, e.message
       end
 
-      # 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
@@ -119,7 +128,7 @@ module Domainic
         old_value = instance.instance_variable_get(:"@#{name}")
 
         coerced_value = value == Undefined ? generate_default(instance) : value
-        coerced_value = @coercer.call(instance, coerced_value) unless coerced_value == Undefined
+        coerced_value = @coercer.call(instance, coerced_value)
 
         @validator.call(instance, coerced_value)
 
@@ -128,7 +137,7 @@ module Domainic
         @callback.call(instance, old_value, coerced_value)
       end
 
-      # 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
       # @rbs () -> bool
@@ -136,10 +145,11 @@ module Domainic
         @default != Undefined
       end
 
-      # 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
       # @rbs (__todo__ new_base) -> Attribute
       def dup_with_base(new_base)
@@ -148,7 +158,7 @@ module Domainic
         dup.tap { |duped| duped.instance_variable_set(:@base, new_base) }
       end
 
-      # Generate the default value for this attribute.
+      # Generate the default value for this attribute
       #
       # @param instance [Object] the instance to generate the default for
       #
@@ -158,11 +168,11 @@ module Domainic
         @default.is_a?(Proc) ? instance.instance_exec(&@default) : @default
       end
 
-      # 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
       # @rbs (Attribute other) -> Attribute
       def merge(other)
@@ -173,7 +183,7 @@ module Domainic
 
       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
@@ -193,7 +203,7 @@ module Domainic
         @validator = Validator.new(self, options.fetch(:validators, []))
       end
 
-      # Initialize a copy of this attribute.
+      # Initialize a copy of this attribute
       #
       # @param source [Attribute] the source attribute
       #
@@ -211,7 +221,7 @@ module Domainic
         super
       end
 
-      # Get this attribute's configuration as options.
+      # Get this attribute's configuration as options
       #
       # @return [Hash] the configuration options
       # @rbs () -> initialize_options
@@ -226,7 +236,7 @@ module Domainic
         }.merge(signature.send(:to_options)) #: initialize_options
       end
 
-      # Validate and apply initialization options.
+      # Validate and apply initialization options
       #
       # @param base [Class, Module] the base class
       # @param options [Hash] the initialization options
@@ -238,7 +248,7 @@ module Domainic
         apply_initialize_options!(base, options)
       end
 
-      # Validate initialization options.
+      # Validate initialization options
       #
       # @param base [Class, Module] the base class
       # @param options [Hash] the initialization options

data/lib/domainic/attributer/attribute_set.rb

@@ -5,14 +5,16 @@ require 'forwardable'
 
 module Domainic
   module Attributer
-    # A class representing an ordered collection of attributes.
+    # A class responsible for managing an ordered collection of attributes
     #
     # This class manages a set of attributes for a given class or module. It maintains
     # attributes in a specific order determined by their type (argument vs option),
     # default values, and position. The collection supports standard operations like
     # adding, selecting, and merging attributes while maintaining proper ownership
-    # relationships with their base class.
+    # relationships with their base class
     #
+    # @api private
+    # @!visibility private
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     class AttributeSet
@@ -21,12 +23,12 @@ module Domainic
       # @rbs @base: __todo__
       # @rbs @lookup: Hash[Symbol, Attribute]
 
-      # Initialize a new AttributeSet.
+      # Initialize a new AttributeSet
       #
       # @param base [Class, Module] the class or module this set belongs to
       # @param attributes [Array<Attribute>] initial attributes to add
       #
-      # @return [void]
+      # @return [AttributeSet] the new AttributeSet instance
       # @rbs (__todo__ base, ?Array[Attribute] attributes) -> void
       def initialize(base, attributes = [])
         @base = base
@@ -34,7 +36,7 @@ module Domainic
         attributes.each { |attribute| add(attribute) }
       end
 
-      # Get an attribute by name.
+      # Get an attribute by name
       #
       # @param attribute_name [String, Symbol] the name of the attribute
       #
@@ -44,16 +46,16 @@ module Domainic
         @lookup[attribute_name.to_sym]
       end
 
-      # Add an attribute to the set.
+      # Add an attribute to the set
       #
       # If an attribute with the same name exists, the attributes are merged.
       # If the attribute belongs to a different base class, it is duplicated
       # with the correct base. After adding, attributes are sorted by type
-      # and position.
+      # and position
       #
       # @param attribute [Attribute] the attribute to add
       #
-      # @raise [ArgumentError] if attribute is invalid
+      # @raise [ArgumentError] if attribute is not a valid {Attribute}
       # @return [void]
       # @rbs (Attribute attribute) -> void
       def add(attribute)
@@ -71,7 +73,7 @@ module Domainic
         nil
       end
 
-      # Check if an attribute exists in the set.
+      # Check if an attribute exists in the set
       #
       # @param attribute_name [String, Symbol] the name to check
       #
@@ -80,7 +82,7 @@ module Domainic
         @lookup.key?(attribute_name.to_sym)
       end
 
-      # Get all attribute names.
+      # Get all attribute names
       #
       # @return [Array<Symbol>] the attribute names
       # @rbs () -> Array[Symbol]
@@ -88,7 +90,7 @@ module Domainic
         @lookup.keys
       end
 
-      # Get all attributes.
+      # Get all attributes
       #
       # @return [Array<Attribute>] the attributes
       # @rbs () -> Array[Attribute]
@@ -99,7 +101,7 @@ module Domainic
       # @rbs! def count: () ?{ (Symbol, Attribute) -> boolish } -> Integer
       def_delegators :@lookup, :count
 
-      # Create a duplicate set for a new base class.
+      # Create a duplicate set for a new base class
       #
       # @param new_base [Class, Module] the new base class
       #
@@ -115,7 +117,7 @@ module Domainic
         end
       end
 
-      # Iterate over attribute name/value pairs.
+      # Iterate over attribute name/value pairs
       #
       # @yield [name, attribute] each name/attribute pair
       # @yieldparam name [Symbol] the attribute name
@@ -132,7 +134,7 @@ module Domainic
       # @rbs! def empty?: () -> bool
       def_delegators :@lookup, :empty?
 
-      # Create a new set excluding specified attributes.
+      # Create a new set excluding specified attributes
       #
       # @param attribute_names [Array<String, Symbol>] names to exclude
       #
@@ -145,7 +147,7 @@ module Domainic
       # @rbs! def length: () -> Integer
       def_delegators :@lookup, :length
 
-      # Merge another set into this one.
+      # Merge another set into this one
       #
       # @param other [AttributeSet] the set to merge
       #
@@ -155,7 +157,7 @@ module Domainic
         self.class.new(other.instance_variable_get(:@base), attributes + other.attributes)
       end
 
-      # Create a new set with rejected attributes.
+      # Create a new set with rejected attributes
       #
       # @yield [name, attribute] each name/attribute pair
       # @yieldparam name [Symbol] the attribute name
@@ -167,7 +169,7 @@ module Domainic
         self.class.new(@base, @lookup.reject(...).values)
       end
 
-      # Create a new set with selected attributes.
+      # Create a new set with selected attributes
       #
       # @yield [name, attribute] each name/attribute pair
       # @yieldparam name [Symbol] the attribute name
@@ -184,10 +186,10 @@ module Domainic
 
       private
 
-      # Sort attributes by type and position.
+      # Sort attributes by type and position
       #
       # Attributes are sorted first by type (required arguments, defaulted arguments,
-      # then options), and then by their position within those groups.
+      # then options), and then by their position within those groups
       #
       # @return [void]
       # @rbs () -> void

data/lib/domainic/attributer/class_methods.rb

@@ -7,81 +7,110 @@ require 'domainic/attributer/undefined'
 
 module Domainic
   module Attributer
-    # A module providing class-level methods for attribute definition.
-    #
-    # This module extends classes that include Domainic::Attributer with methods for
-    # defining and managing attributes. It supports two types of attributes:
+    # This module extends classes that include {Domainic::Attributer} with methods for defining and managing attributes.
+    # It supports two types of attributes:
     # 1. Arguments - Positional parameters that must be provided in a specific order
     # 2. Options - Named parameters that can be provided in any order
     #
+    # @note This module is automatically extended when {Domainic::Attributer} is included in a class
+    #
     # @example Defining arguments and options
     #   class Person
     #     include Domainic::Attributer
     #
-    #     argument :name, ->(value) { value.is_a?(String) }
-    #     argument :age do |value|
-    #       value.is_a?(Integer) && value >= 0
+    #     argument :name, String
+    #     argument :age, Integer do
+    #       validate_with ->(val) { val >= 0 }
     #     end
     #
-    #     option :email, ->(value) { value.is_a?(String) }, default: nil
-    #     option :role do |value|
-    #       %w[admin user guest].include?(value)
+    #     option :email, String, default: nil
+    #     option :role do
+    #       validate_with ->(val) { %w[admin user guest].include?(val) }
     #     end
     #   end
     #
+    #   person = Person.new('Alice', 30, email: 'alice123@gmail.com', role: 'user')
+    #   # => #<Person:0x0000000104bc5f98 @age=30, @email="alice123@gmail.com", @name="Alice", @role="user">
+    #
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     module ClassMethods
       # @rbs @__attributes__: AttributeSet
 
-      # Define a positional argument attribute.
-      #
-      # Arguments are required by default and must be provided in the order they are defined.
-      # They can be type-validated and configured with additional options like defaults
-      # and visibility.
-      #
-      # @param attribute_name [String, Symbol] the name of the attribute
-      # @param type_validator [Proc, Object, nil] optional validation handler for type checking
-      # @param options [Hash] additional configuration options
-      #
-      # @option options [Array<Proc>, Proc] :callbacks handlers for attribute change events (priority over :callback,
-      #   :on_change)
-      # @option options [Array<Proc>, Proc] :callback alias for :callbacks
-      # @option options [Array<Proc, Symbol>, Proc, Symbol] :coerce handlers for value coercion (priority over
-      #   :coercers, :coerce_with)
-      # @option options [Array<Proc, Symbol>, Proc, Symbol] :coercers alias for :coerce
-      # @option options [Array<Proc, Symbol>, Proc, Symbol] :coerce_with alias for :coerce
-      # @option options [Object] :default the default value (priority over :default_generator, :default_value)
-      # @option options [Object] :default_generator alias for :default
-      # @option options [Object] :default_value alias for :default
-      # @option options [String] :desc short description (overridden by :description)
-      # @option options [String] :description description text
-      # @option options [Boolean] :non_nil require non-nil values (priority over :non_null, :non_nullable, :not_nil,
-      #   :not_nilable, :not_null, :not_nullable)
-      # @option options [Boolean] :non_null alias for :non_nil
-      # @option options [Boolean] :non_nullable alias for :non_nil
-      # @option options [Boolean] :not_nil alias for :non_nil
-      # @option options [Boolean] :not_nilable alias for :non_nil
-      # @option options [Boolean] :not_null alias for :non_nil
-      # @option options [Boolean] :not_nullable alias for :non_nil
-      # @option options [Boolean] :null inverse of :non_nil
-      # @option options [Array<Proc>, Proc] :on_change alias for :callbacks
-      # @option options [Boolean] :optional whether attribute is optional (overridden by :required)
-      # @option options [Integer] :position specify order position
-      # @option options [Symbol] :read read visibility (:public, :protected, :private) (priority over :read_access,
-      #   :reader)
-      # @option options [Symbol] :read_access alias for :read
-      # @option options [Symbol] :reader alias for :read
-      # @option options [Boolean] :required whether attribute is required
-      # @option options [Array<Object>, Object] :validate validators for the attribute (priority over :validate_with,
-      #   :validators)
-      # @option options [Array<Object>, Object] :validate_with alias for :validate
-      # @option options [Array<Object>, Object] :validators alias for :validate
-      # @option options [Symbol] :write_access write visibility (:public, :protected, :private) (priority over :writer)
-      # @option options [Symbol] :writer alias for :write_access
-      #
-      # @yield [DSL::AttributeBuilder] optional configuration block
-      # @return [void]
+      # Define a positional argument attribute
+      #
+      # Arguments are required by default and must be provided in the order they are defined unless they have a default
+      # value. They can be type-validated and configured with additional options like defaults and visibility
+      #
+      # @see DSL::AttributeBuilder
+      #
+      # @example Using the options API
+      #   class Person
+      #     argument :name, String
+      #     argument :age, ->(val) { val.is_a?(Integer) && val >= 0 }
+      #     argument :role, default: 'user'
+      #   end
+      #
+      # @example Using the block API
+      #   class Person
+      #     argument :name, String do
+      #       validate_with ->(val) { val.length >= 3 }
+      #     end
+      #
+      #     argument :age, Integer do
+      #       coerce_with ->(val) { val.to_i }
+      #       validate_with ->(val) { val >= 0 }
+      #     end
+      #
+      #     argument :role, String do
+      #       validate_with ->(val) { VALID_USER_ROLES.include?(val) }
+      #       default 'user'
+      #     end
+      #   end
+      #
+      # @overload argument(attribute_name, type_validator = nil, **options)
+      #   @param attribute_name [String, Symbol] the name of the attribute
+      #   @param type_validator [Proc, Object, nil] optional validation handler for type checking
+      #   @param options [Hash{Symbol => Object}] additional configuration options
+      #   @option options [Array<Proc>, Proc] :callbacks handlers for attribute change events (priority over
+      #     :callback, :on_change)
+      #   @option options [Array<Proc>, Proc] :callback alias for :callbacks
+      #   @option options [Array<Proc, Symbol>, Proc, Symbol] :coerce handlers for value coercion (priority over
+      #     :coercers, :coerce_with)
+      #   @option options [Array<Proc, Symbol>, Proc, Symbol] :coercers alias for :coerce
+      #   @option options [Array<Proc, Symbol>, Proc, Symbol] :coerce_with alias for :coerce
+      #   @option options [Object] :default the default value (priority over :default_generator, :default_value)
+      #   @option options [Object] :default_generator alias for :default
+      #   @option options [Object] :default_value alias for :default
+      #   @option options [String] :desc short description (overridden by :description)
+      #   @option options [String] :description description text
+      #   @option options [Boolean] :non_nil require non-nil values (priority over :non_null, :non_nullable, :not_nil,
+      #     :not_nilable, :not_null, :not_nullable)
+      #   @option options [Boolean] :non_null alias for :non_nil
+      #   @option options [Boolean] :non_nullable alias for :non_nil
+      #   @option options [Boolean] :not_nil alias for :non_nil
+      #   @option options [Boolean] :not_nilable alias for :non_nil
+      #   @option options [Boolean] :not_null alias for :non_nil
+      #   @option options [Boolean] :not_nullable alias for :non_nil
+      #   @option options [Boolean] :null inverse of :non_nil
+      #   @option options [Array<Proc>, Proc] :on_change alias for :callbacks
+      #   @option options [Boolean] :optional whether attribute is optional (overridden by :required)
+      #   @option options [Integer] :position specify order position
+      #   @option options [Symbol] :read read visibility (:public, :protected, :private) (priority over :read_access,
+      #     :reader)
+      #   @option options [Symbol] :read_access alias for :read
+      #   @option options [Symbol] :reader alias for :read
+      #   @option options [Boolean] :required whether attribute is required
+      #   @option options [Array<Object>, Object] :validate validators for the attribute (priority over
+      #     :validate_with, :validators)
+      #   @option options [Array<Object>, Object] :validate_with alias for :validate
+      #   @option options [Array<Object>, Object] :validators alias for :validate
+      #   @option options [Symbol] :write_access write visibility (:public, :protected, :private) (priority over
+      #     :writer)
+      #   @option options [Symbol] :writer alias for :write_access
+      #
+      #   @yield [DSL::AttributeBuilder] configuration block for additional attribute settings
+      #   @return [void]
       # @rbs (
       #   String | Symbol attribute_name,
       #   ?Attribute::Validator::handler type_validator,
@@ -127,18 +156,45 @@ module Domainic
         DSL::MethodInjector.inject!(self, attribute)
       end
 
-      # Define a named option attribute.
+      # Define a named option attribute
       #
       # Options are optional by default and can be provided in any order. They can be
-      # type-validated and configured with additional options like defaults and visibility.
+      # type-validated and configured with additional options like defaults and visibility
+      #
+      # @see DSL::AttributeBuilder
+      # @see DSL::AttributeBuilder::OptionParser#initialize
+      #
+      # @example Using the options API
+      #   class Person
+      #     option :email, String
+      #     option :age, ->(val) { val.is_a?(Integer) && val >= 0 }
+      #     option :role, default: 'user'
+      #   end
       #
-      # @overload option(attribute_name, type_validator = Undefined, **options, &block)
+      # @example Using the block API
+      #   class Person
+      #     option :email, String do
+      #       coerce_with ->(val) { val.downcase }
+      #       validate_with ->(val) { URI::MailTo::EMAIL_REGEXP.match?(val) }
+      #     end
+      #
+      #     option :age, Integer do
+      #       coerce_with ->(val) { val.to_i }
+      #       validate_with ->(val) { val >= 0 }
+      #     end
+      #
+      #     option :role, String do
+      #       validate_with ->(val) { VALID_USER_ROLES.include?(val) }
+      #       default 'user'
+      #     end
+      #   end
+      #
+      # @overload option(attribute_name, type_validator = nil, **options)
       #   @param attribute_name [String, Symbol] the name of the attribute
       #   @param type_validator [Proc, Object, nil] optional validation handler for type checking
-      #   @param options [Hash] additional configuration options
-      #
-      #   @option options [Array<Proc>, Proc] :callbacks handlers for attribute change events (priority over :callback,
-      #     :on_change)
+      #   @param options [Hash{Symbol => Object}] additional configuration options
+      #   @option options [Array<Proc>, Proc] :callbacks handlers for attribute change events (priority over
+      #     :callback, :on_change)
       #   @option options [Array<Proc>, Proc] :callback alias for :callbacks
       #   @option options [Array<Proc, Symbol>, Proc, Symbol] :coerce handlers for value coercion (priority over
       #     :coercers, :coerce_with)
@@ -166,18 +222,15 @@ module Domainic
       #   @option options [Symbol] :read_access alias for :read
       #   @option options [Symbol] :reader alias for :read
       #   @option options [Boolean] :required whether attribute is required
-      #   @option options [Array<Object>, Object] :validate validators for the attribute (priority over :validate_with,
-      #     :validators)
+      #   @option options [Array<Object>, Object] :validate validators for the attribute (priority over
+      #     :validate_with, :validators)
       #   @option options [Array<Object>, Object] :validate_with alias for :validate
       #   @option options [Array<Object>, Object] :validators alias for :validate
-      #   @option options [Symbol] :write_access write visibility (:public, :protected, :private)
-      #     (priority over :writer)
+      #   @option options [Symbol] :write_access write visibility (:public, :protected, :private) (priority over
+      #     :writer)
       #   @option options [Symbol] :writer alias for :write_access
       #
-      # @yield [DSL::AttributeBuilder] optional configuration block
-      # @return [void]
-      #
-      #   @yield [DSL::AttributeBuilder] optional configuration block
+      #   @yield [DSL::AttributeBuilder] configuration block for additional attribute settings
       #   @return [void]
       # @rbs (
       #   String | Symbol attribute_name,
@@ -222,10 +275,18 @@ module Domainic
 
       private
 
-      # Handle class inheritance for attributes.
+      # Get the attribute set for this class
+      #
+      # @return [AttributeSet] the set of attributes defined for this class
+      # @rbs () -> AttributeSet
+      def __attributes__
+        @__attributes__ ||= AttributeSet.new(self)
+      end
+
+      # Handle class inheritance for attributes
       #
       # Ensures that subclasses inherit a copy of their parent's attributes while
-      # maintaining proper ownership relationships.
+      # maintaining proper ownership relationships
       #
       # @param subclass [Class] the inheriting class
       # @return [void]
@@ -234,14 +295,6 @@ module Domainic
         super
         subclass.instance_variable_set(:@__attributes__, __attributes__.dup_with_base(subclass))
       end
-
-      # Get the attribute set for this class.
-      #
-      # @return [AttributeSet] the set of attributes defined for this class
-      # @rbs () -> AttributeSet
-      def __attributes__
-        @__attributes__ ||= AttributeSet.new(self)
-      end
     end
   end
 end