MONGOID-5415: Code docs: denote type unions with pipe (#5366)

* Docs--convert to pipe

* More progress

* Fix return values

* More missed values

* More missed items

* Boolean --> true/false

* Update matcher.rb

* Oops

* Update selectable.rb

* Fix tuple

* Fix tuple

* Missed one

* Revert splat

* Revert array tuple

* Revert Array tuple

* - More array tuples
- Remove trailing empty comment lines
- Misc fixes

* Whitespace

* Update regexp.rb

* fix serializable_hash

* fix find

* revert misadditions

* redo extract_attribute note

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

Author: johnnyshields

lib/mongoid/association.rb

@@ -56,7 +56,7 @@ module Association
     # @example Is the document embedded?
     #   address.embedded?
     #
-    # @return [ true, false ] True if the document has a parent document.
+    # @return [ true | false ] True if the document has a parent document.
     def embedded?
       @embedded ||= (cyclic ? _parent.present? : self.class.embedded?)
     end
@@ -66,7 +66,7 @@ def embedded?
     # @example Is the document in an embeds many?
     #   address.embedded_many?
     #
-    # @return [ true, false ] True if in an embeds many.
+    # @return [ true | false ] True if in an embeds many.
     def embedded_many?
       _association && _association.is_a?(Association::Embedded::EmbedsMany)
     end
@@ -76,7 +76,7 @@ def embedded_many?
     # @example Is the document in an embeds one?
     #   address.embedded_one?
     #
-    # @return [ true, false ] True if in an embeds one.
+    # @return [ true | false ] True if in an embeds one.
     def embedded_one?
       _association && _association.is_a?(Association::Embedded::EmbedsOne)
     end
@@ -100,7 +100,7 @@ def association_name
     # @example Is the document in a references many?
     #   post.referenced_many?
     #
-    # @return [ true, false ] True if in a references many.
+    # @return [ true | false ] True if in a references many.
     def referenced_many?
       _association && _association.is_a?(Association::Referenced::HasMany)
     end
@@ -110,7 +110,7 @@ def referenced_many?
     # @example Is the document in a references one?
     #   address.referenced_one?
     #
-    # @return [ true, false ] True if in a references one.
+    # @return [ true | false ] True if in a references one.
     def referenced_one?
       _association && _association.is_a?(Association::Referenced::HasOne)
     end

lib/mongoid/association/accessors.rb

@@ -15,8 +15,8 @@ module Accessors
       # @example Build the association.
       #   person.__build__(:addresses, { :_id => 1 }, association)
       #
-      # @param [ String, Symbol ] name The name of the association.
-      # @param [ Hash, BSON::ObjectId ] object The id or attributes to use.
+      # @param [ String | Symbol ] name The name of the association.
+      # @param [ Hash | BSON::ObjectId ] object The id or attributes to use.
       # @param [ Association ] association The association metadata.
       # @param [ Hash ] selected_fields Fields which were retrieved via #only.
       #   If selected_fields is specified, fields not listed in it will not be
@@ -33,7 +33,7 @@ def __build__(name, object, association, selected_fields = nil)
       # @example Create the association.
       #   person.create_relation(document, association)
       #
-      # @param [ Document, Array<Document> ] object The association target.
+      # @param [ Document | Array<Document> ] object The association target.
       # @param [ Association ] association The association metadata.
       # @param [ Hash ] selected_fields Fields which were retrieved via #only.
       #   If selected_fields is specified, fields not listed in it will not be
@@ -80,7 +80,7 @@ def reset_relation_criteria(name)
       # @example Set the proxy on the document.
       #   person.set(:addresses, addresses)
       #
-      # @param [ String, Symbol ] name The name of the association.
+      # @param [ String | Symbol ] name The name of the association.
       # @param [ Proxy ] relation The association to set.
       #
       # @return [ Proxy ] The association.
@@ -101,7 +101,7 @@ def set_relation(name, relation)
       # @param [ Symbol ] name The name of the association.
       # @param [ Association ] association The association metadata.
       # @param [ Object ] object The object used to build the association.
-      # @param [ true, false ] reload If the association is to be reloaded.
+      # @param [ true | false ] reload If the association is to be reloaded.
       #
       # @return [ Proxy ] The association.
       def get_relation(name, association, object, reload = false)
@@ -225,7 +225,7 @@ def needs_no_database_query?(object, association)
       # @example Is autobuild disabled?
       #   document.without_autobuild?
       #
-      # @return [ true, false ] If autobuild is disabled.
+      # @return [ true | false ] If autobuild is disabled.
       def without_autobuild?
         Threaded.executing?(:without_autobuild)
       end

lib/mongoid/association/bindable.rb

@@ -15,7 +15,7 @@ module Bindable
       #   Binding.new(base, target, association)
       #
       # @param [ Document ] base The base of the binding.
-      # @param [ Document, Array<Document> ] target The target of the binding.
+      # @param [ Document | Array<Document> ] target The target of the binding.
       # @param [ Association ] association The association metadata.
       def initialize(base, target, association)
         @_base, @_target, @_association = base, target, association
@@ -200,7 +200,7 @@ def record_id(_base)
       # @example Set the base association.
       #   binding.set_base_association
       #
-      # @return [ true, false ] If the association changed.
+      # @return [ true | false ] If the association changed.
       def set_base_association
         inverse_association = _association.inverse_association(_target)
         if inverse_association != _association && !inverse_association.nil?

lib/mongoid/association/constrainable.rb

@@ -5,7 +5,6 @@ module Association
 
     # Used for converting foreign key values to the correct type based on the
     # types of ids that the document stores.
-    #
     module Constrainable
 
       # Convert the supplied object to the appropriate type to set as the

lib/mongoid/association/embedded/batchable.rb

@@ -196,7 +196,7 @@ def execute_batch_push(docs)
         # @example Can inserts be performed?
         #   batchable.insertable?
         #
-        # @return [ true, false ] If inserts can be performed.
+        # @return [ true | false ] If inserts can be performed.
         def insertable?
           persistable? && !_assigning? && inserts_valid
         end
@@ -208,7 +208,7 @@ def insertable?
         # @example Are the inserts currently valid.
         #   batchable.inserts_valid
         #
-        # @return [ true, false ] If inserts are currently valid.
+        # @return [ true | false ] If inserts are currently valid.
         def inserts_valid
           @inserts_valid
         end
@@ -220,9 +220,9 @@ def inserts_valid
         # @example Set the flag.
         #   batchable.inserts_valid = true
         #
-        # @param [ true, false ] value The flag.
+        # @param [ true | false ] value The flag.
         #
-        # @return [ true, false ] The flag.
+        # @return [ true | false ] The flag.
         def inserts_valid=(value)
           @inserts_valid = value
         end
@@ -235,7 +235,7 @@ def inserts_valid=(value)
         # @example Normalize the docs.
         #   batchable.normalize_docs(docs)
         #
-        # @param [ Array<Hash, Document> ] docs The docs to normalize.
+        # @param [ Array<Hash | Document> ] docs The docs to normalize.
         #
         # @return [ Array<Document> ] The docs.
         def normalize_docs(docs)

lib/mongoid/association/embedded/cyclic.rb

@@ -88,7 +88,7 @@ def cyclic_parent_name
           # @example Determine the child name.
           #   Role.cyclic_child_name
           #
-          # @param [ true, false ] many Is the a many association?
+          # @param [ true | false ] many Is the a many association?
           #
           # @return [ String ] "child_" plus the class name underscored in
           #   singular or plural form.

lib/mongoid/association/embedded/embedded_in.rb

@@ -75,7 +75,7 @@ def relation
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           !!@options[:polymorphic]
         end

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

@@ -32,7 +32,7 @@ def initialize(base, target, association)
           #
           # @param [ Document ] replacement A document to replace the target.
           #
-          # @return [ Document, nil ] The association or nil.
+          # @return [ Document | nil ] The association or nil.
           def substitute(replacement)
             unbind_one
             unless replacement
@@ -74,7 +74,7 @@ def characterize_one(document)
           # @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?
             _target.persisted? && !_binding? && !_building?
           end

lib/mongoid/association/embedded/embeds_many.rb

@@ -92,7 +92,7 @@ def relation
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!@options[:as]
         end
@@ -101,7 +101,7 @@ def polymorphic?
         #
         # @note Only relevant if the association is polymorphic.
         #
-        # @return [ String, nil ] The field for storing the associated object's type.
+        # @return [ String | nil ] The field for storing the associated object's type.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end

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 | Array<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 | Array<Object> ] args Args to delegate to the target.
           #
           # @return [ Integer ] The total number of persisted embedded docs, as
           #   flagged by the #persisted? method.
@@ -135,7 +135,7 @@ def count(*args, &block)
           #
           # @param [ Document ] document The document to be deleted.
           #
-          # @return [ Document, nil ] The deleted document or nil if nothing deleted.
+          # @return [ Document | nil ] The deleted document or nil if nothing deleted.
           def delete(document)
             execute_callbacks_around(:remove, document) do
               doc = _target.delete_one(document)
@@ -176,7 +176,7 @@ def delete_all(conditions = {})
           #     doc.state == "GA"
           #   end
           #
-          # @return [ Many, Enumerator ] The association or an enumerator if no
+          # @return [ Many | Enumerator ] The association or an enumerator if no
           #   block was provided.
           def delete_if
             if block_given?
@@ -210,7 +210,7 @@ def destroy_all(conditions = {})
           # @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?
             _target.any? { |doc| doc.persisted? }
           end
@@ -287,7 +287,7 @@ def in_memory
           # @param [ Integer ] count The number of documents to pop, or 1 if not
           #   provided.
           #
-          # @return [ Document, Array<Document> ] The popped document(s).
+          # @return [ Document | Array<Document> ] The popped document(s).
           def pop(count = nil)
             if count
               if docs = _target[_target.size - count, _target.size]
@@ -312,7 +312,7 @@ def pop(count = nil)
           # @param [ Integer ] count The number of documents to shift, or 1 if not
           #   provided.
           #
-          # @return [ Document, Array<Document> ] The shifted document(s).
+          # @return [ Document | Array<Document> ] The shifted document(s).
           def shift(count = nil)
             if count
               if _target.size > 0 && docs = _target[0, count]
@@ -429,7 +429,7 @@ 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 [ Symbol | String ] name The name of the method.
           # @param [ Array ] args The method args
           # @param [ Proc ] block Optional block to pass.
           #
@@ -446,7 +446,7 @@ def integrate(document)
           # @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?
           end
@@ -490,7 +490,7 @@ def scope(docs)
           #   relation.remove_all({ :num => 1 }, true)
           #
           # @param [ Hash ] conditions Conditions to filter by.
-          # @param [ true, false ] method :delete or :destroy.
+          # @param [ true | false ] method :delete or :destroy.
           #
           # @return [ Integer ] The number of documents removed.
           def remove_all(conditions = {}, method = :delete)