🚀 [READY FOR REVIEW] MONGOID-5564 Code Docs: Make it a rule to use full namespaces in code doc

docs/contributing/code-documentation.txt

@@ -149,6 +149,31 @@ Formatting
 Type Declaration
 ----------------
 
+- **Namespaces:** Always use fully-namespaced class/module names.
+  Do not use leading colons ``::``.
+
+  .. code-block:: ruby
+
+    # GOOD:
+    # @param [ ActiveSupport::TimeWithZone ] time Time for alarm.
+
+    # BAD:
+    # @param [ TimeWithZone ] time Time for alarm.
+    # @param [ ::ActiveSupport::TimeWithZone ] time Time for alarm.
+
+- **Module Types:** It is acceptable to reference types by a module
+  which they include.
+
+  .. code-block:: ruby
+
+    class Person
+      include ActiveModel::Model
+    end
+
+    # @param [ ActiveModel::Model ] model Any object whose class
+    #   includes ActiveModel::Model. An instance of Person would
+    #   be acceptable here.
+
 - **Type Unions:** Use pipe ``|`` to denote a union of allowed types.
 
   .. code-block:: ruby

lib/mongoid/association/accessors.rb

@@ -23,7 +23,7 @@ module Accessors
       #   If selected_fields is specified, fields not listed in it will not be
       #   accessible in the built document.
       #
-      # @return [ Proxy ] The association.
+      # @return [ Mongoid::Association::Proxy ] The association.
       def __build__(name, object, association, selected_fields = nil)
         relation = create_relation(object, association, selected_fields)
         set_relation(name, relation)
@@ -34,13 +34,13 @@ 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 [ Mongoid::Document | Array<Mongoid::Document> ] object The association target.
       # @param [ Mongoid::Association::Relatable ] 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
       #   accessible in the created association document.
       #
-      # @return [ Proxy ] The association.
+      # @return [ Mongoid::Association::Proxy ] The association.
       def create_relation(object, association, selected_fields = nil)
         type = @attributes[association.inverse_type]
         target = if t = association.build(self, object, type, selected_fields)
@@ -82,9 +82,9 @@ def reset_relation_criteria(name)
       #   person.set(:addresses, addresses)
       #
       # @param [ String | Symbol ] name The name of the association.
-      # @param [ Proxy ] relation The association to set.
+      # @param [ Mongoid::Association::Proxy ] relation The association to set.
       #
-      # @return [ Proxy ] The association.
+      # @return [ Mongoid::Association::Proxy ] The association.
       def set_relation(name, relation)
         instance_variable_set("@_#{name}", relation)
       end
@@ -104,7 +104,7 @@ def set_relation(name, relation)
       # @param [ Object ] object The object used to build the association.
       # @param [ true | false ] reload If the association is to be reloaded.
       #
-      # @return [ Proxy ] The association.
+      # @return [ Mongoid::Association::Proxy ] The association.
       def get_relation(name, association, object, reload = false)
         field_name = database_field_name(name)
 

lib/mongoid/association/bindable.rb

@@ -15,8 +15,8 @@ module Bindable
       # @example Initialize a binding.
       #   Binding.new(base, target, association)
       #
-      # @param [ Document ] base The base of the binding.
-      # @param [ Document | Array<Document> ] target The target of the binding.
+      # @param [ Mongoid::Document ] base The base of the binding.
+      # @param [ Mongoid::Document | Array<Mongoid::Document> ] target The target of the binding.
       # @param [ Mongoid::Association::Relatable ] association The association metadata.
       def initialize(base, target, association)
         @_base, @_target, @_association = base, target, association
@@ -47,7 +47,7 @@ def binding
       # @example Check the inverse definition.
       #   binding.check_inverse!(doc)
       #
-      # @param [ Document ] doc The document getting bound.
+      # @param [ Mongoid::Document ] doc The document getting bound.
       #
       # @raise [ Errors::InverseNotFound ] If no inverse found.
       def check_inverse!(doc)
@@ -63,7 +63,7 @@ def check_inverse!(doc)
 
       # Remove the associated document from the inverse's association.
       #
-      # @param [ Document ] doc The document to remove.
+      # @param [ Mongoid::Document ] doc The document to remove.
       def remove_associated(doc)
         if inverse = _association.inverse(doc)
           if _association.many?
@@ -78,7 +78,7 @@ def remove_associated(doc)
       #
       # This method removes the associated on *_many relationships.
       #
-      # @param [ Document ] doc The document to remove.
+      # @param [ Mongoid::Document ] doc The document to remove.
       # @param [ Symbol ] inverse The name of the inverse.
       def remove_associated_many(doc, inverse)
         # We only want to remove the inverse association when the inverse
@@ -98,7 +98,7 @@ def remove_associated_many(doc, inverse)
       # This method removes associated on belongs_to and embedded_in
       # associations.
       #
-      # @param [ Document ] doc The document to remove.
+      # @param [ Mongoid::Document ] doc The document to remove.
       # @param [ Symbol ] inverse The name of the inverse.
       def remove_associated_in_to(doc, inverse)
         # We only want to remove the inverse association when the inverse
@@ -116,7 +116,7 @@ def remove_associated_in_to(doc, inverse)
       # @example Bind the foreign key.
       #   binding.bind_foreign_key(post, person._id)
       #
-      # @param [ Document ] keyed The document that stores the foreign key.
+      # @param [ Mongoid::Document ] keyed The document that stores the foreign key.
       # @param [ Object ] id The id of the bound document.
       def bind_foreign_key(keyed, id)
         unless keyed.frozen?
@@ -132,7 +132,7 @@ def bind_foreign_key(keyed, id)
       # @example Bind the polymorphic type.
       #   binding.bind_polymorphic_type(post, "Person")
       #
-      # @param [ Document ] typed The document that stores the type field.
+      # @param [ Mongoid::Document ] typed The document that stores the type field.
       # @param [ String ] name The name of the model.
       def bind_polymorphic_type(typed, name)
         if _association.type && !typed.frozen?
@@ -148,7 +148,7 @@ def bind_polymorphic_type(typed, name)
       # @example Bind the polymorphic type.
       #   binding.bind_polymorphic_inverse_type(post, "Person")
       #
-      # @param [ Document ] typed The document that stores the type field.
+      # @param [ Mongoid::Document ] typed The document that stores the type field.
       # @param [ String ] name The name of the model.
       def bind_polymorphic_inverse_type(typed, name)
         if _association.inverse_type && !typed.frozen?
@@ -164,8 +164,8 @@ def bind_polymorphic_inverse_type(typed, name)
       # @example Bind the inverse.
       #   binding.bind_inverse(post, person)
       #
-      # @param [ Document ] doc The base document.
-      # @param [ Document ] inverse The inverse document.
+      # @param [ Mongoid::Document ] doc The base document.
+      # @param [ Mongoid::Document ] inverse The inverse document.
       def bind_inverse(doc, inverse)
         if doc.respond_to?(_association.inverse_setter) && !doc.frozen?
           try_method(doc, _association.inverse_setter, inverse)
@@ -179,7 +179,7 @@ def bind_inverse(doc, inverse)
       # @example Bind the document with the base.
       #   binding.bind_from_relational_parent(doc)
       #
-      # @param [ Document ] doc The document to bind.
+      # @param [ Mongoid::Document ] doc The document to bind.
       def bind_from_relational_parent(doc)
         check_inverse!(doc)
         remove_associated(doc)
@@ -216,7 +216,7 @@ def set_base_association
       # @example Bind the document with the base.
       #   unbinding.unbind_from_relational_parent(doc)
       #
-      # @param [ Document ] doc The document to unbind.
+      # @param [ Mongoid::Document ] doc The document to unbind.
       def unbind_from_relational_parent(doc)
         check_inverse!(doc)
         bind_foreign_key(doc, nil)

lib/mongoid/association/eager.rb

@@ -13,7 +13,7 @@ class Eager
       #
       # @param [ Array<Mongoid::Association::Relatable> ] associations
       #   Associations to eager load
-      # @param [ Array<Document> ] docs Documents to preload the associations
+      # @param [ Array<Mongoid::Document> ] docs Documents to preload the associations
       #
       # @return [ Base ] The eager load preloader
       def initialize(associations, docs)
@@ -84,7 +84,7 @@ def each_loaded_document(&block)
       #   loader.set_on_parent("foo", docs)
       #
       # @param [ ObjectId ] id parent`s id
-      # @param [ Document | Array ] element to push into the parent
+      # @param [ Mongoid::Document | Array ] element to push into the parent
       def set_on_parent(id, element)
         grouped_docs[id].each do |d|
           set_relation(d, element)
@@ -138,8 +138,8 @@ def group_by_key
       # @example Set docs into parent using the current association name.
       #   loader.set_relation(doc, docs)
       #
-      # @param [ Document ] doc The object to set the association on
-      # @param [ Document | Array ] element to set into the parent
+      # @param [ Mongoid::Document ] doc The object to set the association on
+      # @param [ Mongoid::Document | Array ] element to set into the parent
       def set_relation(doc, element)
         doc.set_relation(@association.name, element) unless doc.blank?
       end

lib/mongoid/association/embedded/batchable.rb

@@ -17,7 +17,7 @@ module Batchable
         # @example Execute the batch push.
         #   batchable.batch_insert([ doc_one, doc_two ])
         #
-        # @param [ Array<Document> ] docs The docs to add.
+        # @param [ Array<Mongoid::Document> ] docs The docs to add.
         #
         # @return [ Array<Hash> ] The inserts.
         def batch_insert(docs)
@@ -29,7 +29,7 @@ def batch_insert(docs)
         # @example Clear all docs.
         #   batchable.batch_clear(docs)
         #
-        # @param [ Array<Document> ] docs The docs to clear.
+        # @param [ Array<Mongoid::Document> ] docs The docs to clear.
         #
         # @return [ Array ] The empty array.
         def batch_clear(docs)
@@ -54,7 +54,7 @@ def batch_clear(docs)
         # @example Batch remove the documents.
         #   batchable.batch_remove([ doc_one, doc_two ])
         #
-        # @param [ Array<Document> ] docs The docs to remove.
+        # @param [ Array<Mongoid::Document> ] docs The docs to remove.
         # @param [ Symbol ] method Delete or destroy.
         def batch_remove(docs, method = :delete)
           # If the _id is nil, we cannot use $pull and delete by searching for
@@ -96,7 +96,7 @@ def batch_remove(docs, method = :delete)
         # @example Batch replace the documents.
         #   batchable.batch_replace([ doc_one, doc_two ])
         #
-        # @param [ Array<Document> | Array<Hash> ] docs The docs to replace with.
+        # @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to replace with.
         #
         # @return [ Array<Hash> ] The inserts.
         def batch_replace(docs)
@@ -149,7 +149,7 @@ def add_atomic_sets(sets)
         # @example Perform a batch $set.
         #   batchable.execute_batch_set(docs)
         #
-        # @param [ Array<Document> ] docs The docs to persist.
+        # @param [ Array<Mongoid::Document> ] docs The docs to persist.
         #
         # @return [ Array<Hash> ] The inserts.
         def execute_batch_set(docs)
@@ -172,7 +172,7 @@ def execute_batch_set(docs)
         # @example Perform a batch push.
         #   batchable.execute_batch_push(docs)
         #
-        # @param [ Array<Document> ] docs The docs to persist.
+        # @param [ Array<Mongoid::Document> ] docs The docs to persist.
         #
         # @return [ Array<Hash> ] The inserts.
         def execute_batch_push(docs)
@@ -234,9 +234,9 @@ def inserts_valid=(value)
         # @example Normalize the docs.
         #   batchable.normalize_docs(docs)
         #
-        # @param [ Array<Document> | Array<Hash> ] docs The docs to normalize.
+        # @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to normalize.
         #
-        # @return [ Array<Document> ] The docs.
+        # @return [ Array<Mongoid::Document> ] The docs.
         def normalize_docs(docs)
           if docs.first.is_a?(::Hash)
             docs.map do |doc|
@@ -309,7 +309,7 @@ def selector
         # @example Pre process the documents.
         #   batchable.pre_process_batch_insert(docs)
         #
-        # @param [ Array<Document> ] docs The documents.
+        # @param [ Array<Mongoid::Document> ] docs The documents.
         #
         # @return [ Array<Hash> ] The documents as an array of hashes.
         def pre_process_batch_insert(docs)
@@ -335,7 +335,7 @@ def pre_process_batch_insert(docs)
         # @example Pre process the documents.
         #   batchable.pre_process_batch_remove(docs, :delete)
         #
-        # @param [ Array<Document> ] docs The documents.
+        # @param [ Array<Mongoid::Document> ] docs The documents.
         # @param [ Symbol ] method Delete or destroy.
         #
         # @return [ Array<Hash> ] The documents as hashes.
@@ -362,7 +362,7 @@ def pre_process_batch_remove(docs, method)
         # @example Post process the documents.
         #   batchable.post_process_batch_insert(docs)
         #
-        # @param [ Array<Documents> ] docs The inserted docs.
+        # @param [ Array<Mongoid::Document> ] docs The inserted docs.
         #
         # @return [ Enumerable ] The document enum.
         def post_process_batch_insert(docs)
@@ -380,10 +380,10 @@ def post_process_batch_insert(docs)
         # @example Post process the documents.
         #   batchable.post_process_batch_remove(docs, :delete)
         #
-        # @param [ Array<Document> ] docs The documents.
+        # @param [ Array<Mongoid::Document> ] docs The documents.
         # @param [ Symbol ] method Delete or destroy.
         #
-        # @return [ Array<Document> ] The documents.
+        # @return [ Array<Mongoid::Document> ] The documents.
         def post_process_batch_remove(docs, method)
           docs.each do |doc|
             doc.run_after_callbacks(:destroy) if method == :destroy

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

@@ -58,7 +58,7 @@ def unbind_one
           # @example Check for inverses errors.
           #   binding.check_inverses!(doc)
           #
-          # @param [ Document ] doc The document to check.
+          # @param [ Mongoid::Document ] doc The document to check.
           def check_polymorphic_inverses!(doc)
             if inverses = _association.inverses(doc)
               if inverses.length > 1

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

@@ -16,14 +16,14 @@ module Buildable
           # @example Build the document.
           #   Builder.new(meta, attrs).build
           #
-          # @param [ Document ] base The object.
-          # @param [ Document | Hash ] object The parent hash or document.
+          # @param [ Mongoid::Document ] base The object.
+          # @param [ Mongoid::Document | Hash ] object The parent hash or document.
           # @param [ String ] type Not used in this context.
           # @param [ Hash ] selected_fields Fields which were retrieved via
           #   #only. If selected_fields are specified, fields not listed in it
           #   will not be accessible in the built document.
           #
-          # @return [ Document ] A single document.
+          # @return [ Mongoid::Document ] A single document.
           def build(base, object, type = nil, selected_fields = nil)
             return object unless object.is_a?(Hash)
             if _loading?

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

@@ -16,8 +16,8 @@ class Proxy < Association::One
           # @example Create the new association.
           #   Association::Embedded::EmbeddedIn.new(person, address, association)
           #
-          # @param [ Document ] base The document the association hangs off of.
-          # @param [ Document ] target The target (parent) of the association.
+          # @param [ Mongoid::Document ] base The document the association hangs off of.
+          # @param [ Mongoid::Document ] target The target (parent) of the association.
           # @param [ Mongoid::Association::Relatable ] association The association metadata.
           #
           # @return [ In ] The proxy.
@@ -34,9 +34,9 @@ def initialize(base, target, association)
           # @example Substitute the new document.
           #   person.name.substitute(new_name)
           #
-          # @param [ Document | Hash ] replacement A document to replace the target.
+          # @param [ Mongoid::Document | Hash ] replacement A document to replace the target.
           #
-          # @return [ Document | nil ] The association or nil.
+          # @return [ Mongoid::Document | nil ] The association or nil.
           def substitute(replacement)
             unbind_one
             unless replacement
@@ -67,7 +67,7 @@ def binding
           # @example Set the base association.
           #   object.characterize_one(document)
           #
-          # @param [ Document ] document The document to set the association metadata on.
+          # @param [ Mongoid::Document ] document The document to set the association metadata on.
           def characterize_one(document)
             _base._association ||= _association.inverse_association(document)
           end
@@ -112,7 +112,7 @@ def embedded?
             # @example Get the path calculator.
             #   Proxy.path(document)
             #
-            # @param [ Document ] document The document to calculate on.
+            # @param [ Mongoid::Document ] document The document to calculate on.
             #
             # @return [ Root ] The root atomic path calculator.
             def path(document)