Map the location of the yard documentation and source code as much as possible.

We had previously consolidated everything into the model class, but we
wanted to define it in a natural way in each location. This was a hack
caused by steep's inability to resolve the issue of `class_methods`, but
by reconsidering our stance toward Steep, we changed it to a more
natural way of writing using `class_methods`.

Author: hamajyotan

lib/active_record_compose/attributes.rb

@@ -5,8 +5,6 @@
 require_relative "attributes/querying"
 
 module ActiveRecordCompose
-  # @private
-  #
   # Provides attribute-related functionality for use within ActiveRecordCompose::Model.
   #
   # This module allows you to define attributes on your composed model, including support
@@ -56,47 +54,32 @@ module Attributes
     include ActiveModel::Attributes
 
     included do
+      # @type self: Class
+
       include Querying
 
-      # @type self: Class
       class_attribute :delegated_attributes, instance_writer: false
     end
 
     # steep:ignore:start
 
     class_methods do
-      # Defines the reader and writer for the specified attribute.
-      #
-      # @example
-      #   class AccountRegistration < ActiveRecordCompose::Model
-      #     def initialize(account, attributes = {})
-      #       @account = account
-      #       super(attributes)
-      #       models.push(account)
-      #     end
-      #
-      #     attribute :original_attribute, :string, default: "qux"
-      #     delegate_attribute :name, to: :account
-      #
-      #     private
-      #
-      #     attr_reader :account
-      #   end
-      #
-      #   account = Account.new
-      #   account.name = "foo"
-      #
-      #   registration = AccountRegistration.new(account)
-      #   registration.name         # => "foo" (delegated)
-      #   registration.name?        # => true  (delegated attribute method + `?`)
-      #
-      #   registration.name = "bar" # => updates account.name
-      #   account.name              # => "bar"
-      #   account.name?             # => true
+      # Provides a method of attribute access to the encapsulated model.
       #
-      #   registration.attributes
-      #   # => { "original_attribute" => "qux", "name" => "bar" }
+      # It provides a way to access the attributes of the model it encompasses,
+      # allowing transparent access as if it had those attributes itself.
       #
+      # @param [Array<Symbol, String>] attributes
+      #   attributes A variable-length list of attribute names to delegate.
+      # @param [Symbol, String] to
+      #   The target object to which attributes are delegated (keyword argument).
+      # @param [Boolean] allow_nil
+      #   allow_nil Whether to allow nil values. Defaults to false.
+      # @example Basic usage
+      #   delegate_attribute :name, :email, to: :profile
+      # @example Allowing nil
+      #   delegate_attribute :bio, to: :profile, allow_nil: true
+      # @see Module#delegate for similar behavior in ActiveSupport
       def delegate_attribute(*attributes, to:, allow_nil: false)
         if to.start_with?("@")
           raise ArgumentError, "Instance variables cannot be specified in delegate to. (#{to})"
@@ -109,47 +92,68 @@ def delegate_attribute(*attributes, to:, allow_nil: false)
       end
 
       # Returns a array of attribute name.
-      # Attributes declared with `delegate_attribute` are also merged.
+      # Attributes declared with {.delegate_attribute} are also merged.
       #
+      # @see #attribute_names
       # @return [Array<String>] array of attribute name.
       def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
     end
 
     # steep:ignore:end
 
     # Returns a array of attribute name.
-    # Attributes declared with `delegate_attribute` are also merged.
+    # Attributes declared with {.delegate_attribute} are also merged.
     #
+    #     class Foo < ActiveRecordCompose::Base
+    #       def initialize(attributes = {})
+    #         @account = Account.new
+    #         super
+    #       end
+    #
+    #       attribute :confirmation, :boolean, default: false   # plain attribute
+    #       delegate_attribute :name, to: :account              # delegated attribute
+    #
+    #       private
+    #
+    #       attr_reader :account
+    #     end
+    #
+    #     Foo.attribute_names                                   # Returns the merged state of plain and delegated attributes
+    #     # => ["confirmation" ,"name"]
+    #
+    #     foo = Foo.new
+    #     foo.attribute_names                                   # Similar behavior for instance method version
+    #     # => ["confirmation", "name"]
+    #
+    # @see #attributes
     # @return [Array<String>] array of attribute name.
     def attribute_names = super + delegated_attributes.to_a.map { _1.attribute_name }
 
     # Returns a hash with the attribute name as key and the attribute value as value.
-    # Attributes declared with `delegate_attribute` are also merged.
+    # Attributes declared with {.delegate_attribute} are also merged.
     #
-    # @return [Hash] hash with the attribute name as key and the attribute value as value.
-    # @example
-    #   class AccountRegistration < ActiveRecordCompose::Model
-    #     def initialize(account, attributes = {})
-    #       @account = account
-    #       super(attributes)
-    #       models.push(account)
-    #     end
+    #     class Foo < ActiveRecordCompose::Base
+    #       def initialize(attributes = {})
+    #         @account = Account.new
+    #         super
+    #       end
     #
-    #     attribute :original_attribute, :string, default: "qux"
-    #     delegate_attribute :name, to: :account
+    #       attribute :confirmation, :boolean, default: false   # plain attribute
+    #       delegate_attribute :name, to: :account              # delegated attribute
     #
-    #     private
+    #       private
     #
-    #     attr_reader :account
-    #   end
-    #
-    #   account = Account.new
-    #   account.name = "foo"
+    #       attr_reader :account
+    #     end
     #
-    #   registration = AccountRegistration.new(account)
+    #     foo = Foo.new
+    #     foo.name = "Alice"
+    #     foo.confirmation = true
     #
-    #   registration.attributes # => { "original_attribute" => "qux", "name" => "bar" }
+    #     foo.attributes                                        # Returns the merged state of plain and delegated attributes
+    #     # => { "confirmation" => true, "name" => "Alice" }
     #
+    # @return [Hash<String, Object>] hash with the attribute name as key and the attribute value as value.
     def attributes
       super.merge(*delegated_attributes.to_a.map { _1.attribute_hash(self) })
     end

lib/active_record_compose/callbacks.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module ActiveRecordCompose
-  # @private
-  #
   # Provides hooks into the life cycle of an ActiveRecordCompose model,
   # allowing you to insert custom logic before or after changes to the object's state.
   #
@@ -21,18 +19,48 @@ module Callbacks
     include ActiveModel::Validations::Callbacks
 
     included do
+      # @!method self.before_save(*args, &block)
+      #   Registers a callback to be called before a model is saved.
+
+      # @!method self.around_save(*args, &block)
+      #   Registers a callback to be called around the save of a model.
+
+      # @!method self.after_save(*args, &block)
+      #   Registers a callback to be called after a model is saved.
+
       define_model_callbacks :save
+
+      # @!method self.before_create(*args, &block)
+      #   Registers a callback to be called before a model is created.
+
+      # @!method self.around_create(*args, &block)
+      #   Registers a callback to be called around the creation of a model.
+
+      # @!method self.after_create(*args, &block)
+      #   Registers a callback to be called after a model is created.
+
       define_model_callbacks :create
+
+      # @!method self.before_update(*args, &block)
+      #   Registers a callback to be called before a model is updated.
+
+      # @!method self.around_update(*args, &block)
+      #   Registers a callback to be called around the update of a model.
+
+      # @!method self.after_update(*args, &block)
+      #   Registers a callback to be called after a update is updated.
       define_model_callbacks :update
     end
 
     private
 
+    # @private
     # Evaluate while firing callbacks such as `before_save` `after_save`
     # before and after block evaluation.
     #
     def with_callbacks(&block) = run_callbacks(:save) { run_callbacks(callback_context, &block) }
 
+    # @private
     # Returns the symbol representing the callback context, which is `:create` if the record
     # is new, or `:update` if it has been persisted.
     #

lib/active_record_compose/inspectable.rb

@@ -4,8 +4,6 @@
 require_relative "attributes"
 
 module ActiveRecordCompose
-  # @private
-  #
   # It provides #inspect behavior.
   # It tries to replicate the inspect format provided by ActiveRecord as closely as possible.
   #
@@ -41,6 +39,7 @@ module Inspectable
 
     # steep:ignore:start
 
+    # @private
     FILTERED_MASK =
       Class.new(DelegateClass(::String)) do
         def pretty_print(pp)
@@ -58,6 +57,10 @@ def pretty_print(pp)
     # steep:ignore:start
 
     class_methods do
+      # Returns columns not to expose when invoking {#inspect}.
+      #
+      # @return [Array<Symbol>]
+      # @see #inspect
       def filter_attributes
         if @filter_attributes.nil?
           superclass.filter_attributes
@@ -66,11 +69,16 @@ def filter_attributes
         end
       end
 
+      # Specify columns not to expose when invoking {#inspect}.
+      #
+      # @param [Array<Symbol>] value
+      # @see #inspect
       def filter_attributes=(value)
         @inspection_filter = nil
         @filter_attributes = value
       end
 
+      # @private
       def inspection_filter
         if @filter_attributes.nil?
           superclass.inspection_filter
@@ -94,7 +102,36 @@ def inherited(subclass)
     # steep:ignore:end
 
     # Returns a formatted string representation of the record's attributes.
+    # It tries to replicate the inspect format provided by ActiveRecord as closely as possible.
+    #
+    # @example
+    #   class Model < ActiveRecordCompose::Model
+    #     def initialize(ar_model)
+    #       @ar_model = ar_model
+    #       super
+    #     end
+    #
+    #     attribute :foo, :date, default: -> { Date.today }
+    #     delegate_attribute :bar, to: :ar_model
+    #
+    #     private attr_reader :ar_model
+    #   end
+    #
+    #   m = Model.new(ar_model)
+    #   m.inspect  #=> #<Model:0x00007ff0fe75fe58 foo: "2025-11-14", bar: "bar">
+    #
+    # @example use {.filter_attributes}
+    #   class Model < ActiveRecordCompose::Model
+    #     self.filter_attributes += %i[foo]
+    #
+    #     # ...
+    #   end
+    #
+    #   m = Model.new(ar_model)
+    #   m.inspect  #=> #<Model:0x00007ff0fe75fe58 foo: [FILTERED], bar: "bar">
     #
+    # @return [String] formatted string representation of the record's attributes.
+    # @see .filter_attributes
     def inspect
       inspection =
         if @attributes
@@ -130,6 +167,7 @@ def pretty_print(pp)
 
     private
 
+    # @private
     def format_for_inspect(name, value)
       return value.inspect if value.nil?