0
@@ -1,5 +1,50 @@
0
 module ActiveRecord
0
   module Associations
0
+    # This is the root class of all association proxies:
0
+    #
0
+    #   AssociationProxy
0
+    #     BelongsToAssociation
0
+    #       HasOneAssociation
0
+    #     BelongsToPolymorphicAssociation
0
+    #     AssociationCollection
0
+    #       HasManyAssociation
0
+    #       HasAndBelongsToManyAssociation
0
+    #     HasManyThroughAssociation
0
+    #       HasOneThroughAssociation
0
+    #
0
+    # Association proxies in Active Record are middlemen between the object that
0
+    # holds the association, known as the <i>@owner</i>, and the actual associated
0
+    # object, known as the <i>@target</i>. The kind of association any proxy is
0
+    # about is available in <tt>@reflection</tt>. That's an instance of the class
0
+    # ActiveRecord::Reflection::AssociationReflection.
0
+    #
0
+    # For example, given
0
+    #
0
+    #   class Blog < ActiveRecord::Base
0
+    #     has_many :posts
0
+    #   end
0
+    #
0
+    #   blog = Blog.find(:first)
0
+    #
0
+    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
0
+    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
0
+    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
0
+    #
0
+    # This class has most of the basic instance methods removed, and delegates
0
+    # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a
0
+    # corner case, it even removes the +class+ method and that's why you get
0
+    #
0
+    #   blog.posts.class # => Array
0
+    #
0
+    # though the object behind <tt>blog.posts</tt> is not an Array, but a
0
+    # ActiveRecord::Associations::HasManyAssociation.
0
+    #
0
+    # The <tt>@target</tt> object is not loaded until needed. For example,
0
+    #
0
+    #   blog.posts.count
0
+    #
0
+    # is computed directly through SQL and does not trigger by itself the
0
+    # instantiation of the actual post records.
0
     class AssociationProxy #:nodoc:
0
       alias_method :proxy_respond_to?, :respond_to?
0
       alias_method :proxy_extend, :extend