mongoid 7.5.4 → 8.1.3

data/lib/mongoid/association/referenced/has_and_belongs_to_many/proxy.rb

@@ -21,17 +21,41 @@ module Mongoid
           # @example Concat with other documents.
           #   person.posts.concat([ post_one, post_two ])
           #
-          # @param [ Document, Array<Document> ] args Any number of documents.
+          # @param [ Document... ] *args Any number of documents.
           #
           # @return [ Array<Document> ] The loaded docs.
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
             if doc = docs.first
-              append(doc)
-              _base.add_to_set(foreign_key => doc.public_send(_association.primary_key))
-              if child_persistable?(doc)
-                doc.save
+              append(doc) do
+                # We ignore the changes to the value for the foreign key in the
+                # changed_attributes hash in this block of code for two reasons:
+                #
+                # 1) The add_to_set method deletes the value for the foreign
+                #    key in the changed_attributes hash, but if we enter this
+                #    method with a value for the foreign key in the
+                #    changed_attributes hash, then we want it to exist outside
+                #    this method as well. It's used later on in the Syncable
+                #    module to set the inverse foreign keys.
+                # 2) The reset_unloaded method accesses the value for the foreign
+                #    key on _base, which causes it to get added to the
+                #    changed_attributes hash. This happens because when reading
+                #    a "resizable" attribute, it is automatically added to the
+                #    changed_attributes hash. This is true only for the foreign
+                #    key value for HABTM associations as the other associations
+                #    use strings for their foreign key values. For consistency
+                #    with the other associations, we ignore this addition to
+                #    the changed_attributes hash.
+                #    See MONGOID-4843 for a longer discussion about this.
+                reset_foreign_key_changes do
+                  _base.add_to_set(foreign_key => doc.public_send(_association.primary_key))
+
+                  if child_persistable?(doc)
+                    doc.save
+                  end
+                  reset_unloaded
+                end
               end
             end
             unsynced(_base, foreign_key) and self
@@ -81,12 +105,13 @@ module Mongoid
           #
           # @return [ Document ] The new document.
           def build(attributes = {}, type = nil)
-            doc = Factory.build(type || klass, attributes)
-            _base.public_send(foreign_key).push(doc.public_send(_association.primary_key))
+            doc = Factory.execute_build(type || klass, attributes, execute_callbacks: false)
             append(doc)
             doc.apply_post_processed_defaults
+            _base.public_send(foreign_key).push(doc.public_send(_association.primary_key))
             unsynced(doc, inverse_foreign_key)
             yield(doc) if block_given?
+            doc.run_pending_callbacks
             doc
           end
 
@@ -112,6 +137,10 @@ module Mongoid
             doc
           end
 
+          # Mongoid::Extensions::Array defines Array#delete_one, so we need
+          # to make sure that method behaves reasonably on proxies, too.
+          alias delete_one delete
+
           # Removes all associations between the base document and the target
           # documents by deleting the foreign keys and the references, orphaning
           # the target documents in the process.
@@ -178,6 +207,7 @@ module Mongoid
               push(replacement.compact.uniq)
             else
               reset_unloaded
+              clear_foreign_key_changes
             end
             self
           end
@@ -195,6 +225,32 @@ module Mongoid
 
           private
 
+          # Clears the foreign key from the changed_attributes hash.
+          #
+          # This is, in general, used to clear the foreign key from the
+          # changed_attributes hash for consistency with the other referenced
+          # associations.
+          #
+          # @api private
+          def clear_foreign_key_changes
+            _base.changed_attributes.delete(foreign_key)
+          end
+
+          # Reset the value in the changed_attributes hash for the foreign key
+          # to its value before executing the given block.
+          #
+          # @api private
+          def reset_foreign_key_changes
+            if _base.changed_attributes.key?(foreign_key)
+              fk = _base.changed_attributes[foreign_key].dup
+              yield if block_given?
+              _base.changed_attributes[foreign_key] = fk
+            else
+              yield if block_given?
+              clear_foreign_key_changes
+            end
+          end
+
           # Appends the document to the target array, updating the index on the
           # document at the same time.
           #
@@ -203,11 +259,12 @@ module Mongoid
           #
           # @param [ Document ] document The document to append to the target.
           def append(document)
-            execute_callback :before_add, document
-            _target.push(document)
-            characterize_one(document)
-            bind_one(document)
-            execute_callback :after_add, document
+            execute_callbacks_around(:add, document) do
+              _target.push(document)
+              characterize_one(document)
+              bind_one(document)
+              yield if block_given?
+            end
           end
 
           # Instantiate the binding associated with this association.
@@ -229,7 +286,7 @@ module Mongoid
           #
           # @param [ Document ] doc The document.
           #
-          # @return [ true, false ] If the document can be persisted.
+          # @return [ true | false ] If the document can be persisted.
           def child_persistable?(doc)
             (persistable? || _creating?) &&
                 !(doc.persisted? && _association.forced_nil_inverse?)

data/lib/mongoid/association/referenced/has_and_belongs_to_many.rb

@@ -78,7 +78,7 @@ module Mongoid
 
         # Are ids only saved on this side of the association?
         #
-        # @return [ true, false ] Whether this association has a forced nil inverse.
+        # @return [ true | false ] Whether this association has a forced nil inverse.
         def forced_nil_inverse?
           @forced_nil_inverse ||= @options.key?(:inverse_of) && !@options[:inverse_of]
         end
@@ -119,6 +119,8 @@ module Mongoid
             @options[:inverse_foreign_key]
           elsif @options.key?(:inverse_of)
             inverse_of ? "#{inverse_of.to_s.singularize}#{FOREIGN_KEY_SUFFIX}" : nil
+          elsif inv = inverse_association&.foreign_key
+            inv
           else
             "#{inverse_class_name.demodulize.underscore}#{FOREIGN_KEY_SUFFIX}"
           end
@@ -129,7 +131,7 @@ module Mongoid
         #
         # @param [ Document ] doc The document to be bound.
         #
-        # @return [ true, false ] Whether the document can be bound.
+        # @return [ true | false ] Whether the document can be bound.
         def bindable?(doc)
           forced_nil_inverse? || (!!inverse && doc.fields.keys.include?(foreign_key))
         end
@@ -219,7 +221,7 @@ module Mongoid
         def synced_save
           assoc = self
           inverse_class.set_callback(
-              :save,
+              :persist_parent,
               :after,
               if: ->(doc){ doc._syncable?(assoc) }
           ) do |doc|
@@ -228,6 +230,7 @@ module Mongoid
         end
 
         def create_foreign_key_field!
+          inverse_class.aliased_associations[foreign_key] = name.to_s
           @owner_class.field(
               foreign_key,
               type: FOREIGN_KEY_FIELD_TYPE,

data/lib/mongoid/association/referenced/has_many/enumerable.rb

@@ -28,7 +28,7 @@ module Mongoid
           #
           # @param [ Enumerable ] other The other enumerable.
           #
-          # @return [ true, false ] If the objects are equal.
+          # @return [ true | false ] If the objects are equal.
           def ==(other)
             return false unless other.respond_to?(:entries)
             entries == other.entries
@@ -42,7 +42,7 @@ module Mongoid
           #
           # @param [ Object ] other The object to check.
           #
-          # @return [ true, false ] If the objects are equal in a case.
+          # @return [ true | false ] If the objects are equal in a case.
           def ===(other)
             return false unless other.respond_to?(:entries)
             if Mongoid.legacy_triple_equals
@@ -192,7 +192,7 @@ module Mongoid
           # @example Is the enumerable empty?
           #   enumerable.empty?
           #
-          # @return [ true, false ] If the enumerable is empty.
+          # @return [ true | false ] If the enumerable is empty.
           def empty?
             if _loaded?
               in_memory.empty?
@@ -215,16 +215,16 @@ module Mongoid
           # completely depending on whether it is iterated to completion.
           #
           # This method can take a parameter and a block. The behavior with
-          # either the paramater or the block is delegated to the standard
+          # either the parameter or the block is delegated to the standard
           # library Enumerable module.
           #
           # Note that when Enumerable's any? method is invoked with both
           # a block and a pattern, it only uses the pattern.
           #
-          # @param [ Object ] condition The condition that documents
+          # @param [ Object... ] *args The condition that documents
           #   must satisfy. See Enumerable documentation for details.
           #
-          # @return [ true, false ] If the association has any documents.
+          # @return [ true | false ] If the association has any documents.
           def any?(*args)
             return super if args.any? || block_given?
 
@@ -240,19 +240,15 @@ module Mongoid
           # @note Automatically adding a sort on _id when no other sort is
           #   defined on the criteria has the potential to cause bad performance issues.
           #   If you experience unexpected poor performance when using #first or #last,
-          #   use the option { id_sort: :none }.
-          #   Be aware that #first/#last won't guarantee order in this case.
+          #   use #take instead.
+          #   Be aware that #take won't guarantee order.
           #
-          # @param [ Integer | Hash ] limit_or_opts The number of documents to
-          #   return, or a hash of options.
-          #
-          # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
-          #   Don't apply a sort on _id if no other sort is defined on the criteria.
+          # @param [ Integer ] limit The number of documents to return.
           #
           # @return [ Document ] The first document found.
-          def first(limit_or_opts = nil)
+          def first(limit = nil)
             _loaded.try(:values).try(:first) ||
-                _added[(ul = _unloaded.try(:first, limit_or_opts)).try(:_id)] ||
+                _added[(ul = _unloaded.try(:first, limit)).try(:_id)] ||
                 ul ||
                 _added.values.try(:first)
           end
@@ -265,7 +261,7 @@ module Mongoid
           # @example Initialize the enumerable with an array.
           #   Enumerable.new([ post ])
           #
-          # @param [ Criteria, Array<Document> ] target The wrapped object.
+          # @param [ Criteria | Array<Document> ] target The wrapped object.
           def initialize(target, base = nil, association = nil)
             @_base = base
             @_association = association
@@ -287,7 +283,7 @@ module Mongoid
           #
           # @param [ Document ] doc The document to check.
           #
-          # @return [ true, false ] If the document is in the target.
+          # @return [ true | false ] If the document is in the target.
           def include?(doc)
             return super unless _unloaded
             _unloaded.where(_id: doc._id).exists? || _added.has_key?(doc._id)
@@ -329,20 +325,16 @@ module Mongoid
           # @note Automatically adding a sort on _id when no other sort is
           #   defined on the criteria has the potential to cause bad performance issues.
           #   If you experience unexpected poor performance when using #first or #last,
-          #   use the option { id_sort: :none }.
-          #   Be aware that #first/#last won't guarantee order in this case.
-          #
-          # @param [ Integer | Hash ] limit_or_opts The number of documents to
-          #   return, or a hash of options.
+          #   use #take instead.
+          #   Be aware that #take won't guarantee order.
           #
-          # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
-          #   Don't apply a sort on _id if no other sort is defined on the criteria.
+          # @param [ Integer ] limit The number of documents to return.
           #
           # @return [ Document ] The last document found.
-          def last(limit_or_opts = nil)
+          def last(limit = nil)
             _added.values.try(:last) ||
                 _loaded.try(:values).try(:last) ||
-                _added[(ul = _unloaded.try(:last, limit_or_opts)).try(:_id)] ||
+                _added[(ul = _unloaded.try(:last, limit)).try(:_id)] ||
                 ul
           end
 
@@ -360,7 +352,7 @@ module Mongoid
           # @example Is the enumerable _loaded?
           #   enumerable._loaded?
           #
-          # @return [ true, false ] If the enumerable has been _loaded.
+          # @return [ true | false ] If the enumerable has been _loaded.
           def _loaded?
             !!@executed
           end
@@ -413,11 +405,11 @@ module Mongoid
           # @example Does the enumerable respond to the method?
           #   enumerable.respond_to?(:sum)
           #
-          # @param [ String, Symbol ] name The name of the method.
-          # @param [ true, false ] include_private Whether to include private
+          # @param [ String | Symbol ] name The name of the method.
+          # @param [ true | false ] include_private Whether to include private
           #   methods.
           #
-          # @return [ true, false ] Whether the enumerable responds.
+          # @return [ true | false ] Whether the enumerable responds.
           def respond_to?(name, include_private = false)
             [].respond_to?(name, include_private) || super
           end

data/lib/mongoid/association/referenced/has_many/proxy.rb

@@ -25,7 +25,7 @@ module Mongoid
           # @example Concat with other documents.
           #   person.posts.concat([ post_one, post_two ])
           #
-          # @param [ Document, Array<Document> ] args Any number of documents.
+          # @param [ Document... ] *args Any number of documents.
           #
           # @return [ Array<Document> ] The loaded docs.
           def <<(*args)
@@ -71,10 +71,11 @@ module Mongoid
           #
           # @return [ Document ] The new document.
           def build(attributes = {}, type = nil)
-            doc = Factory.build(type || klass, attributes)
+            doc = Factory.execute_build(type || klass, attributes, execute_callbacks: false)
             append(doc)
             doc.apply_post_processed_defaults
             yield(doc) if block_given?
+            doc.run_pending_callbacks
             doc.run_callbacks(:build) { doc }
             doc
           end
@@ -92,16 +93,22 @@ module Mongoid
           #
           # @return [ Document ] The matching document.
           def delete(document)
-            execute_callback :before_remove, document
-            _target.delete(document) do |doc|
-              if doc
-                unbind_one(doc)
-                cascade!(doc) if !_assigning?
+            execute_callbacks_around(:remove, document) do
+              _target.delete(document) do |doc|
+                if doc
+                  unbind_one(doc)
+                  cascade!(doc) if !_assigning?
+                end
+              end.tap do
+                reset_unloaded
               end
-              execute_callback :after_remove, doc
             end
           end
 
+          # Mongoid::Extensions::Array defines Array#delete_one, so we need
+          # to make sure that method behaves reasonably on proxies, too.
+          alias delete_one delete
+
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
@@ -165,7 +172,7 @@ module Mongoid
           # @example Are there persisted documents?
           #   person.posts.exists?
           #
-          # @return [ true, false ] True is persisted documents exist, false if not.
+          # @return [ true | false ] True is persisted documents exist, false if not.
           def exists?
             criteria.exists?
           end
@@ -181,6 +188,9 @@ module Mongoid
           # of those found by the current Criteria object for which the block
           # returns a truthy value.
           #
+          # @note Each argument can be an individual id, an array of ids or
+          #   a nested array. Each array will be flattened.
+          #
           # @example Find by an id.
           #   person.posts.find(BSON::ObjectId.new)
           #
@@ -193,7 +203,7 @@ module Mongoid
           # @note This will keep matching documents in memory for iteration
           #   later.
           #
-          # @param [ BSON::ObjectId, Array<BSON::ObjectId> ] args The ids.
+          # @param [ [ Object | Array<Object> ]... ] *args The ids.
           # @param [ Proc ] block Optional block to pass.
           #
           # @return [ Document | Array<Document> | nil ] A document or matching documents.
@@ -325,7 +335,7 @@ module Mongoid
           #   relation.with_add_callbacks(document, false)
           #
           # @param [ Document ] document The document to append to the target.
-          # @param [ true, false ] already_related Whether the document is already related
+          # @param [ true | false ] already_related Whether the document is already related
           #   to the target.
           def with_add_callbacks(document, already_related)
             execute_callback :before_add, document unless already_related
@@ -340,7 +350,7 @@ module Mongoid
           #
           # @param [ Document ] document The document to possibly append to the target.
           #
-          # @return [ true, false ] Whether the document is already related to the base and the
+          # @return [ true | false ] Whether the document is already related to the base and the
           #   association is persisted.
           def already_related?(document)
             document.persisted? &&
@@ -388,7 +398,7 @@ module Mongoid
           #
           # @param [ Document ] document The document to cascade on.
           #
-          # @return [ true, false ] If the association is destructive.
+          # @return [ true | false ] If the association is destructive.
           def cascade!(document)
             if persistable?
               case _association.dependent
@@ -407,11 +417,11 @@ module Mongoid
           #
           # If the method exists on the array, use the default proxy behavior.
           #
-          # @param [ Symbol, String ] name The name of the method.
-          # @param [ Array ] args The method args
+          # @param [ Symbol | String ] name The name of the method.
+          # @param [ Object... ] *args The method args
           # @param [ Proc ] block Optional block to pass.
           #
-          # @return [ Criteria, Object ] A Criteria or return value from the target.
+          # @return [ Criteria | Object ] A Criteria or return value from the target.
           ruby2_keywords def method_missing(name, *args, &block)
             if _target.respond_to?(name)
               _target.send(name, *args, &block)
@@ -447,7 +457,7 @@ module Mongoid
           # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the association is persistable.
+          # @return [ true | false ] If the association is persistable.
           def persistable?
             !_binding? && (_creating? || _base.persisted? && !_building?)
           end
@@ -469,8 +479,8 @@ module Mongoid
             selector = conditions || {}
             removed = klass.send(method, selector.merge!(criteria.selector))
             _target.delete_if do |doc|
-              if doc._matches?(selector)
-                unbind_one(doc) and true
+              doc._matches?(selector).tap do |b|
+                unbind_one(doc) if b
               end
             end
             removed

data/lib/mongoid/association/referenced/has_many.rb

@@ -118,7 +118,7 @@ module Mongoid
         #
         # @note Only relevant for polymorphic associations.
         #
-        # @return [ String, nil ] The type field.
+        # @return [ String | nil ] The type field.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -140,7 +140,7 @@ module Mongoid
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!as
         end
@@ -150,7 +150,7 @@ module Mongoid
         #
         # @param [ Document ] doc The document to be bound.
         #
-        # @return [ true, false ] Whether the document can be bound.
+        # @return [ true | false ] Whether the document can be bound.
         def bindable?(doc)
           forced_nil_inverse? || (!!inverse && doc.fields.keys.include?(foreign_key))
         end

data/lib/mongoid/association/referenced/has_one/buildable.rb

@@ -53,7 +53,7 @@ module Mongoid
           end
 
           def execute_query(object, base)
-            query_criteria(object, base).limit(1).first(id_sort: :none)
+            query_criteria(object, base).take
           end
 
           def with_polymorphic_criterion(criteria, base)

data/lib/mongoid/association/referenced/has_one/nested_builder.rb

@@ -60,7 +60,7 @@ module Mongoid
           # @example Is the id acceptable?
           #   one.acceptable_id?
           #
-          # @return [ true, false ] If the id part of the logic will allow an update.
+          # @return [ true | false ] If the id part of the logic will allow an update.
           def acceptable_id?
             id = convert_id(existing.class, attributes[:_id])
             existing._id == id || id.nil? || (existing._id != id && update_only?)
@@ -71,7 +71,7 @@ module Mongoid
           # @example Can the existing object be deleted?
           #   one.delete?
           #
-          # @return [ true, false ] If the association should be deleted.
+          # @return [ true | false ] If the association should be deleted.
           def delete?
             destroyable? && !attributes[:_id].nil?
           end
@@ -81,7 +81,7 @@ module Mongoid
           # @example Is the object destroyable?
           #   one.destroyable?({ :_destroy => "1" })
           #
-          # @return [ true, false ] If the association can potentially be
+          # @return [ true | false ] If the association can potentially be
           #   destroyed.
           def destroyable?
             [ 1, "1", true, "true" ].include?(destroy) && allow_destroy?
@@ -92,7 +92,7 @@ module Mongoid
           # @example Is the document to be replaced?
           #   one.replace?
           #
-          # @return [ true, false ] If the document should be replaced.
+          # @return [ true | false ] If the document should be replaced.
           def replace?
             !existing && !destroyable? && !attributes.blank?
           end
@@ -102,7 +102,7 @@ module Mongoid
           # @example Should the document be updated?
           #   one.update?
           #
-          # @return [ true, false ] If the object should have its attributes updated.
+          # @return [ true | false ] If the object should have its attributes updated.
           def update?
             existing && !destroyable? && acceptable_id?
           end

data/lib/mongoid/association/referenced/has_one/proxy.rb

@@ -49,17 +49,14 @@ module Mongoid
           #
           # @return [ One ] The association.
           def substitute(replacement)
-            # If the same object currently associated is being assigned,
-            # rebind the association and save the target but do not destroy
-            # the target.
-
-            unbind_one
-            if persistable?
-              # TODO can this entire method be skipped if self == replacement?
-              if _association.destructive? && self != replacement
-                send(_association.dependent)
-              else
-                save if persisted?
+            if self != replacement
+              unbind_one
+              if persistable?
+                if _association.destructive?
+                  send(_association.dependent)
+                else
+                  save if persisted?
+                end
               end
             end
             HasOne::Proxy.new(_base, replacement, _association) if replacement
@@ -82,7 +79,7 @@ module Mongoid
           # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the association is persistable.
+          # @return [ true | false ] If the association is persistable.
           def persistable?
             _base.persisted? && !_binding? && !_building?
           end

data/lib/mongoid/association/referenced/has_one.rb

@@ -92,7 +92,7 @@ module Mongoid
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!as
         end
@@ -101,7 +101,7 @@ module Mongoid
         #
         # @note Only relevant for polymorphic associations.
         #
-        # @return [ String, nil ] The type field.
+        # @return [ String | nil ] The type field.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -111,7 +111,7 @@ module Mongoid
         #
         # @param [ Document ] doc The document to be bound.
         #
-        # @return [ true, false ] Whether the document can be bound.
+        # @return [ true | false ] Whether the document can be bound.
         def bindable?(doc)
           forced_nil_inverse? || (!!inverse && doc.fields.keys.include?(foreign_key))
         end

data/lib/mongoid/association/referenced/syncable.rb

@@ -16,7 +16,7 @@ module Mongoid
         #
         # @param [ Association ] association The association metadata.
         #
-        # @return [ true, false ] If we can sync.
+        # @return [ true | false ] If we can sync.
         def _syncable?(association)
           !_synced?(association.foreign_key) && send(association.foreign_key_check)
         end
@@ -38,7 +38,7 @@ module Mongoid
         #
         # @param [ String ] foreign_key The foreign key.
         #
-        # @return [ true, false ] If we can sync.
+        # @return [ true | false ] If we can sync.
         def _synced?(foreign_key)
           !!_synced[foreign_key]
         end
@@ -67,8 +67,8 @@ module Mongoid
         #
         # @return [ Object ] The updated values.
         def update_inverse_keys(association)
-          if changes.has_key?(association.foreign_key)
-            old, new = changes[association.foreign_key]
+          if previous_changes.has_key?(association.foreign_key)
+            old, new = previous_changes[association.foreign_key]
             adds, subs = new - (old || []), (old || []) - new
 
             # If we are autosaving we don't want a duplicate to get added - the

data/lib/mongoid/association/reflections.rb

@@ -13,7 +13,7 @@ module Mongoid
       # @example Find association metadata by name.
       #   person.reflect_on_association(:addresses)
       #
-      # @param [ String, Symbol ] name The name of the association to find.
+      # @param [ String | Symbol ] name The name of the association to find.
       #
       # @return [ Association ] The matching association metadata.
       def reflect_on_association(name)
@@ -25,7 +25,7 @@ module Mongoid
       # @example Find multiple association metadata by macro.
       #   person.reflect_on_all_associations(:embeds_many)
       #
-      # @param [ Array<Symbol> ] macros The association macros.
+      # @param [ Symbol... ] *macros The association macros.
       #
       # @return [ Array<Association> ] The matching association metadata.
       def reflect_on_all_association(*macros)
@@ -39,7 +39,7 @@ module Mongoid
         # @example Find association metadata by name.
         #   Person.reflect_on_association(:addresses)
         #
-        # @param [ String, Symbol ] name The name of the association to find.
+        # @param [ String | Symbol ] name The name of the association to find.
         #
         # @return [ Association ] The matching association metadata.
         def reflect_on_association(name)
@@ -51,7 +51,7 @@ module Mongoid
         # @example Find multiple association metadata by macro.
         #   Person.reflect_on_all_associations(:embeds_many)
         #
-        # @param [ Array<Symbol> ] macros The association macros.
+        # @param [ Symbol... ] *macros The association macros.
         #
         # @return [ Array<Association> ] The matching association metadata.
         def reflect_on_all_associations(*macros)