MONGOID-5415: Add splats to code docs (#5400)

* Correct splats in docs.

* Requested fixes

* Line wrap

Co-authored-by: shields <[email protected]>

Author: johnnyshields

lib/mongoid/association/accessors.rb

@@ -251,7 +251,7 @@ def without_autobuild
       # @example Parse the args.
       #   doc.parse_args(:name => "Joe")
       #
-      # @param [ Array ] args The arguments.
+      # @param [ Hash... ] *args The arguments.
       #
       # @return [ Array<Hash> ] The attributes and options.
       def parse_args(*args)

lib/mongoid/association/builders.rb

@@ -27,7 +27,7 @@ module Builders
       # @example Parse the args.
       #   doc.parse_args(:name => "Joe")
       #
-      # @param [ Array ] args The arguments.
+      # @param [ Hash... ] *args The arguments.
       #
       # @return [ Array<Hash> ] The attributes and options.
       def parse_args(*args)

lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -19,7 +19,7 @@ class Proxy < Association::Many
           # @example Push a document.
           #   person.addresses.push(address)
           #
-          # @param [ Document | Array<Document> ] args Any number of documents.
+          # @param [ Document... ] *args Any number of documents.
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
@@ -117,7 +117,7 @@ def clear
           # @example Use #persisted? inside block to count persisted documents.
           #   person.addresses.count { |a| a.persisted? && a.country == "FR" }
           #
-          # @param [ Object | Array<Object> ] args Args to delegate to the target.
+          # @param [ Object... ] *args Args to delegate to the target.
           #
           # @return [ Integer ] The total number of persisted embedded docs, as
           #   flagged by the #persisted? method.
@@ -235,7 +235,7 @@ def exists?
           # @example Finds the first matching document using a block.
           #   person.addresses.find { |addr| addr.state == 'CA' }
           #
-          # @param [ Array<Object> ] args Various arguments.
+          # @param [ Object... ] *args Various arguments.
           # @param [ Proc ] block Optional block to pass.
           #
           # @return [ Document | Array<Document> | nil ] A document or matching documents.
@@ -430,10 +430,10 @@ def integrate(document)
           # 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 [ 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)
             return super if _target.respond_to?(name)
             klass.send(:with_scope, criteria) do

lib/mongoid/association/proxy.rb

@@ -118,7 +118,7 @@ def characterize_one(document)
       # to the target of the proxy. This can be overridden in special cases.
       #
       # @param [ String | Symbol ] name The name of the method.
-      # @param [ Array ] args The arguments passed to the method.
+      # @param [ Object... ] *args The arguments passed to the method.
       ruby2_keywords def method_missing(name, *args, &block)
         _target.send(name, *args, &block)
       end

lib/mongoid/association/referenced/counter_cache.rb

@@ -13,7 +13,7 @@ module CounterCache
         # @example Reset the given counter cache
         #   post.reset_counters(:comments)
         #
-        # @param [ Symbol | Array ] counters One or more counter caches to reset
+        # @param [ Symbol... ] *counters One or more counter caches to reset.
         def reset_counters(*counters)
           self.class.with(persistence_context) do |_class|
             _class.reset_counters(self, *counters)
@@ -30,7 +30,7 @@ module ClassMethods
           #   Post.reset_counters('50e0edd97c71c17ea9000001', :comments)
           #
           # @param [ String ] id The id of the object that will be reset.
-          # @param [ Symbol | Array ] counters One or more counter caches to reset
+          # @param [ Symbol... ] *counters One or more counter caches to reset.
           def reset_counters(id, *counters)
             document = id.is_a?(Document) ? id : find(id)
             counters.each do |name|

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

@@ -21,7 +21,7 @@ class Proxy < Referenced::HasMany::Proxy
           # @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)

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

@@ -215,13 +215,13 @@ def empty?
           # 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.

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

@@ -25,7 +25,7 @@ class Proxy < Association::Many
           # @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)
@@ -199,7 +199,7 @@ def exists?
           # @note This will keep matching documents in memory for iteration
           #   later.
           #
-          # @param [ Object | Array<Object> ] *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.
@@ -414,7 +414,7 @@ def cascade!(document)
           # 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 [ Object... ] *args The method args
           # @param [ Proc ] block Optional block to pass.
           #
           # @return [ Criteria | Object ] A Criteria or return value from the target.

lib/mongoid/association/reflections.rb

@@ -25,7 +25,7 @@ def reflect_on_association(name)
       # @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)
@@ -51,7 +51,7 @@ def reflect_on_association(name)
         # @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)

lib/mongoid/attributes/dynamic.rb

@@ -115,7 +115,7 @@ def inspect_dynamic_fields
       #   document.method_missing(:test)
       #
       # @param [ String | Symbol ] name The name of the method.
-      # @param [ Array ] args The arguments to the method.
+      # @param [ Object... ] *args The arguments to the method.
       #
       # @return [ Object ] The result of the method call.
       def method_missing(name, *args)

lib/mongoid/attributes/nested.rb

@@ -33,8 +33,8 @@ module ClassMethods
         #     accepts_nested_attributes_for :addresses, :game, :posts
         #   end
         #
-        # @param [ Array<Symbol> | Hash ] args A list of association names, followed
-        #   by a hash of options.
+        # @param [ Symbol..., Hash ] *args A list of association names, followed
+        #   by an optional hash of options.
         #
         # @option *args [ true | false ] :allow_destroy Can deletion occur?
         # @option *args [ Proc | Symbol ] :reject_if Block or symbol pointing

lib/mongoid/attributes/readonly.rb

@@ -61,7 +61,7 @@ module ClassMethods
         #     attr_readonly :name, :genre
         #   end
         #
-        # @param [ Array<Symbol> ] names The names of the fields.
+        # @param [ Symbol... ] *names The names of the fields.
         def attr_readonly(*names)
           names.each do |name|
             readonly_attributes << database_field_name(name)

lib/mongoid/contextual/atomic.rb

@@ -150,7 +150,7 @@ def set(sets)
       # @example Unset the field on the matches.
       #   context.unset(:name)
       #
-      # @param [ String | Symbol | Array<String | Symbol> | Hash ] args
+      # @param [ [ String | Symbol | Array<String | Symbol> | Hash ]... ] *args
       #   The name(s) of the field(s) to unset.
       #   If a Hash is specified, its keys will be used irrespective of what
       #   each key's value is, even if the value is nil or false.

lib/mongoid/contextual/memory.rb

@@ -237,7 +237,7 @@ def limit(value)
       # @example Get the values in memory.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
@@ -255,9 +255,9 @@ def pluck(*fields)
       # @example Get the values in memory.
       #   context.pick(:name)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pick.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
       #
-      # @return [ Object, Array<Object> ] The picked values.
+      # @return [ Object | Array<Object> ] The picked values.
       def pick(*fields)
         if doc = documents.first
           pluck_from_doc(doc, *fields)
@@ -742,9 +742,9 @@ def retrieve_value_at_path(document, field_path)
       # Pluck the field values from the given document.
       #
       # @param [ Document ] doc The document to pluck from.
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
       #
-      # @return [ Object, Array<Object> ] The plucked values.
+      # @return [ Object | Array<Object> ] The plucked values.
       def pluck_from_doc(doc, *fields)
         if fields.length == 1
           retrieve_value_at_path(doc, fields.first)

lib/mongoid/contextual/mongo.rb

@@ -321,7 +321,7 @@ def map_reduce(map, reduce)
       # @example Pluck a field.
       #   context.pluck(:_id)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pluck,
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck,
       #   which may include nested fields using dot-notation.
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
@@ -362,7 +362,7 @@ def pluck(*fields)
       # @example Pick a field.
       #   context.pick(:_id)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pick.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
       #
       # @return [ Object | Array<Object> ] The picked values.
       def pick(*fields)
@@ -519,7 +519,7 @@ def sort(values = nil, &block)
       # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
       #   an update should apply.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil, opts = {})
         update_documents(attributes, :update_one, opts)
       end
@@ -535,7 +535,7 @@ def update(attributes = nil, opts = {})
       # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
       #   an update should apply.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil, opts = {})
         update_documents(attributes, :update_many, opts)
       end

lib/mongoid/contextual/none.rb

@@ -88,7 +88,7 @@ def exists?; false; end
       # @example Get the values for null context.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *_fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pluck.
       #
       # @return [ Array ] An empty Array.
       def pluck(*_fields)
@@ -100,9 +100,9 @@ def pluck(*_fields)
       # @example Get the value for null context.
       #   context.pick(:name)
       #
-      # @param [ String | Symbol ] *_fields Field or fields to pick.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pick.
       #
-      # @return [ nil ] Always reeturn nil.
+      # @return [ nil ] Always return nil.
       def pick(*_fields)
         nil
       end

lib/mongoid/criteria.rb

@@ -88,7 +88,7 @@ def ==(other)
     # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
     #   enumerator = criteria.find(-> { "Default Band" })
     #
-    # @param [ Object | Array<Object> ] *args The ids.
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s).
     # @param [ Proc ] block Optional block to pass.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
@@ -284,7 +284,7 @@ def empty_and_chainable?
     # @example Limit the fields returned from the database.
     #   Band.only(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ [ Symbol | Array<Symbol> ]... ] *args The field name(s).
     #
     # @return [ Criteria ] The cloned criteria.
     def only(*args)
@@ -318,7 +318,7 @@ def read(value = nil)
     # @example Exclude fields returned from the database.
     #   Band.without(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ Symbol... ] *args The field name(s).
     #
     # @return [ Criteria ] The cloned criteria.
     def without(*args)
@@ -385,7 +385,8 @@ def type(types)
     # @example Add a javascript selection.
     #   criteria.where("this.name == 'syd'")
     #
-    # @param [ String | Hash ] expression The javascript or standard selection.
+    # @param [ [ Hash | String ]... ] *args The standard selection
+    #   or javascript string.
     #
     # @raise [ UnsupportedJavascript ] If provided a string and the criteria
     #   is embedded.
@@ -495,7 +496,7 @@ def initialize_copy(other)
     #   criteria.method_missing(:name)
     #
     # @param [ Symbol ] name The method name.
-    # @param [ Array ] args The arguments.
+    # @param [ Object... ] *args The arguments.
     #
     # @return [ Object ] The result of the method call.
     ruby2_keywords def method_missing(name, *args, &block)

lib/mongoid/criteria/findable.rb

@@ -21,7 +21,7 @@ def execute_or_raise(ids, multi)
         multi ? result : result.first
       end
 
-      # Find the matchind document(s) in the criteria for the provided ids.
+      # Find the matching document(s) in the criteria for the provided id(s).
       #
       # @note Each argument can be an individual id, an array of ids or
       #   a nested array. Each array will be flattened.
@@ -32,7 +32,7 @@ def execute_or_raise(ids, multi)
       # @example Find by multiple ids.
       #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
       #
-      # @param [ Object | Array<Object> ] *args The ids to search for.
+      # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
       #
       # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)

lib/mongoid/criteria/includable.rb

@@ -21,8 +21,8 @@ module Includable
       # @example Eager load the provided associations.
       #   Person.includes(:posts, :game)
       #
-      # @param [ Array<Symbol>, Array<Hash> ] relations The names of the associations to eager
-      #   load.
+      # @param [ [ Symbol | Hash ]... ] *relations The names of the association(s)
+      #   to eager load.
       #
       # @return [ Criteria ] The cloned criteria.
       def includes(*relations)
@@ -70,7 +70,8 @@ def add_inclusion(association, parent = nil)
       #   association originates.
       # @param [ String ] parent The name of the association above this one in
       #   the inclusion tree, if it is a nested inclusion.
-      # @param relations_list The names of the associations to eager load.
+      # @param [ [ Symbol | Hash | Array<Symbol | Hash> ]... ] *relations_list
+      #   The names of the association(s) to eager load.
       def extract_includes_list(_parent_class, parent, *relations_list)
         relations_list.flatten.each do |relation_object|
           if relation_object.is_a?(Hash)