Merge pull request rails#55107 from rails/fxn/through-docs

Document through + polymorphic

Author: fxn

activerecord/lib/active_record/associations.rb

@@ -1208,8 +1208,10 @@ module ClassMethods
         # [+:as+]
         #   Specifies a polymorphic interface (See #belongs_to).
         # [+:through+]
-        #   Specifies an association through which to perform the query. This can be any other type
-        #   of association, including other <tt>:through</tt> associations. Options for <tt>:class_name</tt>,
+        #   Specifies an association through which to perform the query.
+        #
+        #   This can be any other type of association, including other <tt>:through</tt> associations,
+        #   but it cannot be a polymorphic association. Options for <tt>:class_name</tt>,
         #   <tt>:primary_key</tt> and <tt>:foreign_key</tt> are ignored, as the association uses the
         #   source reflection.
         #
@@ -1411,10 +1413,12 @@ def has_many(name, scope = nil, **options, &extension)
         # [+:as+]
         #   Specifies a polymorphic interface (See #belongs_to).
         # [+:through+]
-        #   Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt>,
-        #   <tt>:primary_key</tt>, and <tt>:foreign_key</tt> are ignored, as the association uses the
-        #   source reflection. You can only use a <tt>:through</tt> query through a #has_one
-        #   or #belongs_to association on the join model.
+        #   Specifies an association through which to perform the query.
+        #
+        #   This can be any other type of association, including other <tt>:through</tt> associations,
+        #   but it cannot be a polymorphic association. Options for <tt>:class_name</tt>, <tt>:primary_key</tt>,
+        #   and <tt>:foreign_key</tt> are ignored, as the association uses the source reflection. You can only
+        #   use a <tt>:through</tt> query through a #has_one or #belongs_to association on the join model.
         #
         #   If the association on the join model is a #belongs_to, the collection can be modified
         #   and the records on the <tt>:through</tt> model will be automatically created and removed

guides/source/association_basics.md

@@ -953,7 +953,7 @@ object, use the `collection.build` method.
 A [`has_many :through`][`has_many`] association is often used to set up a
 many-to-many relationship with another model. This association indicates that
 the declaring model can be matched with zero or more instances of another model
-by proceeding _through_ a third model.
+by proceeding _through_ an intermediate "join" model.
 
 For example, consider a medical practice where patients make appointments to see
 physicians. The relevant association declarations could look like this:
@@ -1012,6 +1012,9 @@ In this migration the `physicians` and `patients` tables are created with a
 created with `physician_id` and `patient_id` columns, establishing the
 many-to-many relationship between `physicians` and `patients`.
 
+INFO: The through association can be any type of association, including other
+through associations, but it cannot be a polymorphic association.
+
 You could also consider using a [composite primary
 key](active_record_composite_primary_keys.html) for the join table in the
 `has_many :through` relationship like below:
@@ -1150,6 +1153,9 @@ class CreateAccountHistories < ActiveRecord::Migration[8.1]
 end
 ```
 
+INFO: The through association can be any type of association, including other
+through associations, but it cannot be a polymorphic association.
+
 ### `has_and_belongs_to_many`
 
 A [`has_and_belongs_to_many`][] association creates a direct many-to-many