mongoid 8.0.1 → 8.0.3

data/lib/mongoid/attributes.rb

@@ -25,9 +25,9 @@ module Mongoid
     # @example Is the attribute present?
     #   person.attribute_present?("title")
     #
-    # @param [ String, Symbol ] name The name of the attribute.
+    # @param [ String | Symbol ] name The name of the attribute.
     #
-    # @return [ true, false ] True if present, false if not.
+    # @return [ true | false ] True if present, false if not.
     def attribute_present?(name)
       attribute = read_raw_attribute(name)
       !attribute.blank? || attribute == false
@@ -50,9 +50,9 @@ module Mongoid
     # @example Does the document have the attribute?
     #   model.has_attribute?(:name)
     #
-    # @param [ String, Symbol ] name The name of the attribute.
+    # @param [ String | Symbol ] name The name of the attribute.
     #
-    # @return [ true, false ] If the key is present in the attributes.
+    # @return [ true | false ] If the key is present in the attributes.
     def has_attribute?(name)
       attributes.key?(name.to_s)
     end
@@ -63,9 +63,9 @@ module Mongoid
     # @example Does the document have the attribute before it was assigned?
     #   model.has_attribute_before_type_cast?(:name)
     #
-    # @param [ String, Symbol ] name The name of the attribute.
+    # @param [ String | Symbol ] name The name of the attribute.
     #
-    # @return [ true, false ] If the key is present in the
+    # @return [ true | false ] If the key is present in the
     #   attributes_before_type_cast.
     def has_attribute_before_type_cast?(name)
       attributes_before_type_cast.key?(name.to_s)
@@ -80,7 +80,7 @@ module Mongoid
     # @example Read an attribute (alternate syntax.)
     #   person[:title]
     #
-    # @param [ String, Symbol ] name The name of the attribute to get.
+    # @param [ String | Symbol ] name The name of the attribute to get.
     #
     # @return [ Object ] The value of the attribute.
     def read_attribute(name)
@@ -113,7 +113,7 @@ module Mongoid
     # @example Read an attribute before type cast.
     #   person.read_attribute_before_type_cast(:price)
     #
-    # @param [ String, Symbol ] name The name of the attribute to get.
+    # @param [ String | Symbol ] name The name of the attribute to get.
     #
     # @return [ Object ] The value of the attribute before type cast, if
     #   available. Otherwise, the value of the attribute.
@@ -132,7 +132,7 @@ module Mongoid
     # @example Remove the attribute.
     #   person.remove_attribute(:title)
     #
-    # @param [ String, Symbol ] name The name of the attribute to remove.
+    # @param [ String | Symbol ] name The name of the attribute to remove.
     #
     # @raise [ Errors::ReadonlyAttribute ] If the field cannot be removed due
     #   to being flagged as reaodnly.
@@ -157,7 +157,7 @@ module Mongoid
     # @example Write the attribute (alternate syntax.)
     #   person[:title] = "Mr."
     #
-    # @param [ String, Symbol ] name The name of the attribute to update.
+    # @param [ String | Symbol ] name The name of the attribute to update.
     # @param [ Object ] value The value to set for the attribute.
     def write_attribute(name, value)
       validate_writable_field_name!(name.to_s)
@@ -237,7 +237,7 @@ module Mongoid
     #
     # @param [ String ] name The name of the attribute.
     #
-    # @return [ true, false ] If the attribute is missing.
+    # @return [ true | false ] If the attribute is missing.
     def attribute_missing?(name)
       !Projector.new(__selected_fields).attribute_or_path_allowed?(name)
     end
@@ -261,7 +261,7 @@ module Mongoid
     # @example Is the string in dot syntax.
     #   model.hash_dot_syntax?
     #
-    # @return [ true, false ] If the string contains a "."
+    # @return [ true | false ] If the string contains a "."
     def hash_dot_syntax?(string)
       string.include?(".")
     end
@@ -271,7 +271,7 @@ module Mongoid
     # @example Get the value typecasted.
     #   person.typed_value_for(:title, :sir)
     #
-    # @param [ String, Symbol ] key The field name.
+    # @param [ String | Symbol ] key The field name.
     # @param [ Object ] value The uncast value.
     #
     # @return [ Object ] The cast value.

data/lib/mongoid/cacheable.rb

@@ -15,7 +15,7 @@ module Mongoid
     # plural model name.
     #
     # If new_record?     - will append /new
-    # If not             - will append /id-updated_at.to_s(cache_timestamp_format)
+    # If not             - will append /id-updated_at.to_formatted_s(cache_timestamp_format)
     # Without updated_at - will append /id
     #
     # This is usually called inside a cache() block
@@ -26,7 +26,7 @@ module Mongoid
     # @return [ String ] the string with or without updated_at
     def cache_key
       return "#{model_key}/new" if new_record?
-      return "#{model_key}/#{_id}-#{updated_at.utc.to_s(cache_timestamp_format)}" if do_or_do_not(:updated_at)
+      return "#{model_key}/#{_id}-#{updated_at.utc.to_formatted_s(cache_timestamp_format)}" if do_or_do_not(:updated_at)
       "#{model_key}/#{_id}"
     end
   end

data/lib/mongoid/changeable.rb

@@ -21,7 +21,7 @@ module Mongoid
     # @example Has the document changed?
     #   model.changed?
     #
-    # @return [ true, false ] If the document is changed.
+    # @return [ true | false ] If the document is changed.
     def changed?
       changes.values.any? { |val| val } || children_changed?
     end
@@ -30,7 +30,7 @@ module Mongoid
     #
     # @note This intentionally only considers children and not descendants.
     #
-    # @return [ true, false ] If any children have changed.
+    # @return [ true | false ] If any children have changed.
     def children_changed?
       _children.any?(&:changed?)
     end
@@ -102,7 +102,7 @@ module Mongoid
     # @example Remove a flagged change.
     #   model.remove_change(:field)
     #
-    # @param [ Symbol, String ] name The name of the field.
+    # @param [ Symbol | String ] name The name of the field.
     def remove_change(name)
       changed_attributes.delete(name.to_s)
     end
@@ -162,7 +162,7 @@ module Mongoid
     #
     # @param [ String ] attr The name of the attribute.
     #
-    # @return [ true, false ] Whether the attribute has changed.
+    # @return [ true | false ] Whether the attribute has changed.
     def attribute_changed?(attr)
       attr = database_field_name(attr)
       return false unless changed_attributes.key?(attr)
@@ -176,7 +176,7 @@ module Mongoid
     #
     # @param [ String ] attr The name of the attribute.
     #
-    # @return [ true, false ] If the attribute differs.
+    # @return [ true | false ] If the attribute differs.
     def attribute_changed_from_default?(attr)
       field = fields[attr]
       return false unless field

data/lib/mongoid/clients/options.rb

@@ -12,7 +12,7 @@ module Mongoid
       #     m.save
       #   end
       #
-      # @param [ Hash, Mongoid::PersistenceContext ] options_or_context
+      # @param [ Hash | Mongoid::PersistenceContext ] options_or_context
       #   The storage options or a persistence context.
       #
       # @option options [ String | Symbol ] :collection The collection name.

data/lib/mongoid/clients/validators/storage.rb

@@ -17,7 +17,7 @@ module Mongoid
         #   Storage.validate(:collection_name)
         #
         # @param [ Class ] klass The model class.
-        # @param [ Hash, String, Symbol ] options The provided options.
+        # @param [ Hash | String | Symbol ] options The provided options.
         def validate(klass, options)
           valid_keys?(options) or raise Errors::InvalidStorageOptions.new(klass, options)
           valid_parent?(klass) or raise Errors::InvalidStorageParent.new(klass)
@@ -31,7 +31,7 @@ module Mongoid
         #
         # @param [ Class ] klass
         #
-        # @return [ true, false ] If the class is valid
+        # @return [ true | false ] If the class is valid.
         def valid_parent?(klass)
           !klass.superclass.include?(Mongoid::Document)
         end
@@ -45,7 +45,7 @@ module Mongoid
         #
         # @param [ Hash ] options The options hash.
         #
-        # @return [ true, false ] If all keys are valid.
+        # @return [ true | false ] If all keys are valid.
         def valid_keys?(options)
           return false unless options.is_a?(::Hash)
           options.keys.all? do |key|

data/lib/mongoid/config/validators/client.rb

@@ -37,7 +37,7 @@ module Mongoid
         # @example Validate the client has database.
         #   validator.validate_client_database(:default, {})
         #
-        # @param [ String, Symbol ] name The config key.
+        # @param [ String | Symbol ] name The config key.
         # @param [ Hash ] config The configuration.
         def validate_client_database(name, config)
           if no_database_or_uri?(config)
@@ -52,7 +52,7 @@ module Mongoid
         # @example Validate the client has hosts.
         #   validator.validate_client_hosts(:default, {})
         #
-        # @param [ String, Symbol ] name The config key.
+        # @param [ String | Symbol ] name The config key.
         # @param [ Hash ] config The configuration.
         def validate_client_hosts(name, config)
           if no_hosts_or_uri?(config)
@@ -68,7 +68,7 @@ module Mongoid
         # @example Validate the uri and options.
         #   validator.validate_client_uri(:default, {})
         #
-        # @param [ String, Symbol ] name The config key.
+        # @param [ String | Symbol ] name The config key.
         # @param [ Hash ] config The configuration.
         def validate_client_uri(name, config)
           if both_uri_and_standard?(config)
@@ -86,7 +86,7 @@ module Mongoid
         #
         # @param [ Hash ] config The configuration options.
         #
-        # @return [ true, false ] If no database or uri is defined.
+        # @return [ true | false ] If no database or uri is defined.
         def no_database_or_uri?(config)
           !config.has_key?(:database) && !config.has_key?(:uri)
         end
@@ -101,7 +101,7 @@ module Mongoid
         #
         # @param [ Hash ] config The configuration options.
         #
-        # @return [ true, false ] If no hosts or uri is defined.
+        # @return [ true | false ] If no hosts or uri is defined.
         def no_hosts_or_uri?(config)
           !config.has_key?(:hosts) && !config.has_key?(:uri)
         end
@@ -116,7 +116,7 @@ module Mongoid
         #
         # @param [ Hash ] config The configuration options.
         #
-        # @return [ true, false ] If both standard and uri are defined.
+        # @return [ true | false ] If both standard and uri are defined.
         def both_uri_and_standard?(config)
           config.has_key?(:uri) && config.keys.any? do |key|
             STANDARD.include?(key.to_sym)

data/lib/mongoid/config.rb

@@ -131,7 +131,7 @@ module Mongoid
     # @example Is Mongoid configured?
     #   config.configured?
     #
-    # @return [ true, false ] If Mongoid is configured.
+    # @return [ true | false ] If Mongoid is configured.
     def configured?
       clients.key?(:default)
     end
@@ -172,7 +172,7 @@ module Mongoid
     #   Mongoid.load!("/path/to/mongoid.yml")
     #
     # @param [ String ] path The path to the file.
-    # @param [ String, Symbol ] environment The environment to load.
+    # @param [ String | Symbol ] environment The environment to load.
     def load!(path, environment = nil)
       settings = Environment.load_yaml(path, environment)
       if settings.present?
@@ -225,9 +225,9 @@ module Mongoid
     # @example Override the database globally.
     #   config.override_database(:optional)
     #
-    # @param [ String, Symbol ] name The name of the database.
+    # @param [ String | Symbol ] name The name of the database.
     #
-    # @return [ String, Symbol ] The global override.
+    # @return [ String | Symbol ] The global override.
     def override_database(name)
       Threaded.database_override = name
     end
@@ -237,9 +237,9 @@ module Mongoid
     # @example Override the client globally.
     #   config.override_client(:optional)
     #
-    # @param [ String, Symbol ] name The name of the client.
+    # @param [ String | Symbol ] name The name of the client.
     #
-    # @return [ String, Symbol ] The global override.
+    # @return [ String | Symbol ] The global override.
     def override_client(name)
       Threaded.client_override = name ? name.to_s : nil
     end
@@ -310,7 +310,7 @@ module Mongoid
     # @example Is the application using passenger?
     #   config.running_with_passenger?
     #
-    # @return [ true, false ] If the app is deployed on Passenger.
+    # @return [ true | false ] If the app is deployed on Passenger.
     def running_with_passenger?
       @running_with_passenger ||= defined?(PhusionPassenger)
     end

data/lib/mongoid/contextual/aggregable/memory.rb

@@ -9,7 +9,7 @@ module Mongoid
         # Get all the aggregate values for the provided field.
         # Provided for interface consistency with Aggregable::Mongo.
         #
-        # @param [ String, Symbol ] field The field name.
+        # @param [ String | Symbol ] field The field name.
         #
         # @return [ Hash ] A Hash containing the aggregate values.
         #   If no documents are present, then returned Hash will have

data/lib/mongoid/contextual/aggregable/mongo.rb

@@ -20,7 +20,7 @@ module Mongoid
         #   #   "avg" => 750.0
         #   # }
         #
-        # @param [ String, Symbol ] field The field name.
+        # @param [ String | Symbol ] field The field name.
         #
         # @return [ Hash ] A Hash containing the aggregate values.
         #   If no documents are found, then returned Hash will have
@@ -64,7 +64,7 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to max.
         #
-        # @return [ Float, Document ] The max value or document with the max
+        # @return [ Float | Document ] The max value or document with the max
         #   value.
         def max(field = nil)
           block_given? ? super() : aggregates(field)["max"]
@@ -84,7 +84,7 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to min.
         #
-        # @return [ Float, Document ] The min value or document with the min
+        # @return [ Float | Document ] The min value or document with the min
         #   value.
         def min(field = nil)
           block_given? ? super() : aggregates(field)["min"]
@@ -115,7 +115,7 @@ module Mongoid
         # @example Get the pipeline.
         #   aggregable.pipeline(:likes)
         #
-        # @param [ String, Symbol ] field The name of the field.
+        # @param [ String | Symbol ] field The name of the field.
         #
         # @return [ Array ] The array of pipeline operators.
         def pipeline(field)

data/lib/mongoid/contextual/aggregable/none.rb

@@ -11,7 +11,7 @@ module Mongoid
         # Get all the aggregate values for the provided field in null context.
         # Provided for interface consistency with Aggregable::Mongo.
         #
-        # @param [ String, Symbol ] _field The field name.
+        # @param [ String | Symbol ] _field The field name.
         #
         # @return [ Hash ] A Hash with count, sum of 0 and max, min, avg of nil.
         def aggregates(_field)

data/lib/mongoid/contextual/atomic.rb

@@ -150,7 +150,7 @@ module Mongoid
       # @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.

data/lib/mongoid/contextual/geo_near.rb

@@ -16,7 +16,7 @@ module Mongoid
       # @example Get the average distance.
       #   geo_near.average_distance
       #
-      # @return [ Float, nil ] The average distance.
+      # @return [ Float | nil ] The average distance.
       def average_distance
         average = stats["avgDistance"]
         (average.nil? || average.nan?) ? nil : average
@@ -46,7 +46,7 @@ module Mongoid
       # @example Provide the distance multiplier.
       #   geo_near.distance_multiplier(13113.1)
       #
-      # @param [ Integer, Float ] value The distance multiplier.
+      # @param [ Integer | Float ] value The distance multiplier.
       #
       # @return [ GeoNear ] The GeoNear wrapper.
       def distance_multiplier(value)
@@ -98,9 +98,9 @@ module Mongoid
       # @example Get the max distance.
       #   geo_near.max_distance
       #
-      # @param [ Integer, Float ] value The maximum distance.
+      # @param [ Integer | Float ] value The maximum distance.
       #
-      # @return [ GeoNear, Float ] The GeoNear command or the value.
+      # @return [ GeoNear | Float ] The GeoNear command or the value.
       def max_distance(value = nil)
         if value
           command[:maxDistance] = value
@@ -115,7 +115,7 @@ module Mongoid
       # @example Set the min distance.
       #   geo_near.min_distance(0.5)
       #
-      # @param [ Integer, Float ] value The minimum distance.
+      # @param [ Integer | Float ] value The minimum distance.
       #
       # @return [ GeoNear ] The GeoNear command.
       def min_distance(value)
@@ -139,7 +139,7 @@ module Mongoid
       # @example Set the unique flag.
       #   geo_near.unique(false)
       #
-      # @param [ true, false ] value Whether to return unique documents.
+      # @param [ true | false ] value Whether to return unique documents.
       #
       # @return [ GeoNear ] The command.
       def unique(value = true)
@@ -211,7 +211,7 @@ module Mongoid
       # @example Get the documents.
       #   geo_near.documents
       #
-      # @return [ Array, Cursor ] The documents.
+      # @return [ Array | Cursor ] The documents.
       def documents
         results["results"].map do |attributes|
           doc = Factory.from_db(criteria.klass, attributes["obj"], criteria)

data/lib/mongoid/contextual/memory.rb

@@ -25,7 +25,7 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @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
@@ -110,7 +110,7 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
-      # @return [ true, false ] If the count is more than zero.
+      # @return [ true | false ] If the count is more than zero.
       def exists?
         any?
       end
@@ -244,7 +244,7 @@ module Mongoid
       #
       # @param [ String | Symbol ] *fields Field(s) to pluck.
       #
-      # @return [ Array ] The array of plucked values.
+      # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
         if Mongoid.legacy_pluck_distinct
           documents.pluck(*fields)
@@ -318,7 +318,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for the document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil)
         update_documents(attributes, [ first ])
       end
@@ -330,7 +330,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for each document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil)
         update_documents(attributes, entries)
       end

data/lib/mongoid/contextual/mongo.rb

@@ -109,7 +109,7 @@ module Mongoid
       # @example Get the distinct values.
       #   context.distinct(:name)
       #
-      # @param [ String, Symbol ] field The name of the field.
+      # @param [ String | Symbol ] field The name of the field.
       #
       # @return [ Array<Object> ] The distinct values for the field.
       def distinct(field)
@@ -157,7 +157,7 @@ module Mongoid
       # @note We don't use count here since Mongo does not use counted
       #   b-tree indexes.
       #
-      # @return [ true, false ] If the count is more than zero.
+      # @return [ true | false ] If the count is more than zero.
       def exists?
         !!(view.projection(_id: 1).limit(1).first)
       end
@@ -181,9 +181,9 @@ module Mongoid
       # @param [ Hash ] update The updates.
       # @param [ Hash ] options The command options.
       #
-      # @option options [ :before, :after ] :return_document Return the updated document
+      # @option options [ :before | :after ] :return_document Return the updated document
       #   from before or after update.
-      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
+      # @option options [ true | false ] :upsert Create the document if it doesn't exist.
       #
       # @return [ Document ] The result of the command.
       def find_one_and_update(update, options = {})
@@ -201,9 +201,9 @@ module Mongoid
       # @param [ Hash ] replacement The replacement.
       # @param [ Hash ] options The command options.
       #
-      # @option options [ :before, :after ] :return_document Return the updated document
+      # @option options [ :before | :after ] :return_document Return the updated document
       #   from before or after update.
-      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
+      # @option options [ true | false ] :upsert Create the document if it doesn't exist.
       #
       # @return [ Document ] The result of the command.
       def find_one_and_replace(replacement, options = {})
@@ -397,9 +397,9 @@ module Mongoid
       # @example Pluck a field.
       #   context.pluck(:_id)
       #
-      # @param [ String, Symbol, Array ] fields Fields to pluck.
+      # @param [ String | Symbol ] *fields Field(s) to pluck.
       #
-      # @return [ Array<Object, Array> ] The plucked values.
+      # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
         # Multiple fields can map to the same field name. For example, plucking
         # a field and its _translations field map to the same field in the database.
@@ -434,9 +434,9 @@ module Mongoid
       # @example Pick a field.
       #   context.pick(:_id)
       #
-      # @param [ String, Symbol, Array ] fields Fields 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)
         limit(1).pluck(*fields).first
       end
@@ -586,7 +586,7 @@ module Mongoid
       # @param [ Hash ] attributes The updates.
       # @param [ Symbol ] method The method to use.
       #
-      # @return [ true, false ] If the update succeeded.
+      # @return [ true | false ] If the update succeeded.
       def update_documents(attributes, method = :update_one, opts = {})
         return false unless attributes
         attributes = Hash[attributes.map { |k, v| [klass.database_field_name(k.to_s), v] }]
@@ -654,7 +654,7 @@ module Mongoid
       # @example Get the documents for iteration.
       #   context.documents_for_iteration
       #
-      # @return [ Array<Document>, Mongo::Collection::View ] The docs to iterate.
+      # @return [ Array<Document> | Mongo::Collection::View ] The docs to iterate.
       def documents_for_iteration
         return view unless eager_loadable?
         docs = view.map{ |doc| Factory.from_db(klass, doc, criteria) }
@@ -764,7 +764,7 @@ module Mongoid
       #
       # @param [ String ] field_name The name of the field to demongoize.
       # @param [ Object ] value The value to demongoize.
-      # @param [ Boolean ] is_translation The field we are retrieving is an
+      # @param [ true | false ] is_translation The field we are retrieving is an
       #   _translations field.
       #
       # @return [ Object ] The demongoized value.
@@ -778,7 +778,7 @@ module Mongoid
       #
       # @param [ Field ] field The field to use to demongoize.
       # @param [ Object ] value The value to demongoize.
-      # @param [ Boolean ] is_translation The field we are retrieving is an
+      # @param [ true | false ] is_translation The field we are retrieving is an
       #   _translations field.
       #
       # @return [ Object ] The demongoized value.

data/lib/mongoid/contextual/none.rb

@@ -40,7 +40,7 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @return [ true, false ] If the objects are equal.
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         other.is_a?(None)
       end
@@ -88,7 +88,7 @@ module Mongoid
       # @example Get the values for null context.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *_fields Field or fields to pluck.
+      # @param [ String | Symbol ] *_fields Field(s) to pluck.
       #
       # @return [ Array ] An empty Array.
       def pluck(*_fields)

data/lib/mongoid/contextual/queryable.rb

@@ -14,7 +14,7 @@ module Mongoid
       # @example Is the context empty?
       #   context.blank?
       #
-      # @return [ true, false ] If the context is empty.
+      # @return [ true | false ] If the context is empty.
       def blank?
         !exists?
       end

data/lib/mongoid/contextual.rb

@@ -30,7 +30,7 @@ module Mongoid
     # @example Get the context.
     #   criteria.context
     #
-    # @return [ Memory, Mongo ] The context.
+    # @return [ Memory | Mongo ] The context.
     def context
       @context ||= create_context
     end
@@ -45,7 +45,7 @@ module Mongoid
     # @example Create the context.
     #   contextual.create_context
     #
-    # @return [ Mongo, Memory ] The context.
+    # @return [ Mongo | Memory ] The context.
     def create_context
       return None.new(self) if empty_and_chainable?
       embedded ? Memory.new(self) : Mongo.new(self)

data/lib/mongoid/criteria/findable.rb

@@ -10,11 +10,11 @@ module Mongoid
       #   criteria.execute_or_raise(id)
       #
       # @param [ Object ] ids The arguments passed.
-      # @param [ true, false ] multi Whether there arguments were a list.
+      # @param [ true | false ] multi Whether there arguments were a list.
       #
       # @raise [ Errors::DocumentNotFound ] If nothing returned.
       #
-      # @return [ Document, Array<Document> ] The document(s).
+      # @return [ Document | Array<Document> ] The document(s).
       def execute_or_raise(ids, multi)
         result = multiple_from_db(ids)
         check_for_missing_documents!(result, ids)
@@ -23,15 +23,18 @@ module Mongoid
 
       # Find the matchind document(s) in the criteria for the provided ids.
       #
+      # @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.
       #   criteria.find(BSON::ObjectId.new)
       #
       # @example Find by multiple ids.
       #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
       #
-      # @param [ Array<BSON::ObjectId> ] args The ids to search for.
+      # @param [ Object | Array<Object> ] *args The ids to search for.
       #
-      # @return [ Array<Document>, Document ] The matching document(s).
+      # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)
         ids = args.__find_args__
         raise_invalid if ids.any?(&:nil?)

data/lib/mongoid/criteria/includable.rb

@@ -66,7 +66,7 @@ module Mongoid
 
       # Iterate through the list of relations and create the inclusions list.
       #
-      # @param [ Class, String, Symbol ] _parent_class The class from which the
+      # @param [ Class | String | Symbol ] _parent_class The class from which the
       #   association originates.
       # @param [ String ] parent The name of the association above this one in
       #   the inclusion tree, if it is a nested inclusion.