Clarify collection proxy docs

The docs for `ActiveRecord::Associations::CollectionProxy` describe
`ActiveRecord::Associations::Association`. I've moved them to
association and rewrote collection proxy's docs to be more applicable to
what the class actually does.`

[ci skip]

2 files changed, 25 insertions, 11 deletions

diff --git a/activerecord/lib/active_record/associations/association.rb b/activerecord/lib/active_record/associations/association.rb
index 5d0927f17d..0bb63b97ae 100644
--- a/activerecord/lib/active_record/associations/association.rb
+++ b/activerecord/lib/active_record/associations/association.rb
@@ -17,6 +17,23 @@ module ActiveRecord
     #     CollectionAssociation
     #       HasManyAssociation + ForeignAssociation
     #         HasManyThroughAssociation + ThroughAssociation
+    #
+    # Associations in Active Record are middlemen between the object that
+    # holds the association, known as the <tt>owner</tt>, and the associated
+    # result set, known as the <tt>target</tt>. Association metadata is available in
+    # <tt>reflection</tt>, which is an instance of <tt>ActiveRecord::Reflection::AssociationReflection</tt>.
+    #
+    # For example, given
+    #
+    #   class Blog < ActiveRecord::Base
+    #     has_many :posts
+    #   end
+    #
+    #   blog = Blog.first
+    #
+    # The association of <tt>blog.posts</tt> has the object +blog+ as its
+    # <tt>owner</tt>, the collection of its posts as <tt>target</tt>, and
+    # the <tt>reflection</tt> object represents a <tt>:has_many</tt> macro.
     class Association #:nodoc:
       attr_reader :owner, :target, :reflection
 
diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index 78993cee8a..edcb44f0fc 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -2,11 +2,8 @@
 
 module ActiveRecord
   module Associations
-    # Association proxies in Active Record are middlemen between the object that
-    # holds the association, known as the <tt>@owner</tt>, and the actual associated
-    # object, known as the <tt>@target</tt>. The kind of association any proxy is
-    # about is available in <tt>@reflection</tt>. That's an instance of the class
-    # ActiveRecord::Reflection::AssociationReflection.
+    # Collection proxies in Active Record are middlemen between an
+    # <tt>association</tt>, and its <tt>target</tt> result set.
     #
     # For example, given
     #
@@ -16,14 +13,14 @@ module ActiveRecord
     #
     #   blog = Blog.first
     #
-    # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as
-    # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and
-    # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro.
+    # The collection proxy returned by <tt>blog.posts</tt> is built from a
+    # <tt>:has_many</tt> <tt>association</tt>, and delegates to a collection
+    # of posts as the <tt>target</tt>.
     #
-    # This class delegates unknown methods to <tt>@target</tt> via
-    # <tt>method_missing</tt>.
+    # This class delegates unknown methods to the <tt>association</tt>'s
+    # relation class via a delegate cache.
     #
-    # The <tt>@target</tt> object is not \loaded until needed. For example,
+    # The <tt>target</tt> result set is not loaded until needed. For example,
     #
     #   blog.posts.count
     #