MONGOID-5570 Code Docs: Add missing documentation (#5559)

* Add missing documentation

* Cleanup

---------

Co-authored-by: Dmitry Rybakov <[email protected]>

Author: johnnyshields

lib/mongoid.rb

@@ -31,15 +31,16 @@
 require "mongoid/warnings"
 require "mongoid/utils"
 
-# If we are using Rails then we will include the Mongoid railtie. This has all
-# the nifty initializers that Mongoid needs.
+# If we are using Rails then we will include the Mongoid railtie.
+# This configures initializers required to integrate Mongoid with Rails.
 if defined?(Rails)
   require "mongoid/railtie"
 end
 
-# add english load path by default
+# Add English locale config to load path by default.
 I18n.load_path << File.join(File.dirname(__FILE__), "config", "locales", "en.yml")
 
+# Top-level module for project.
 module Mongoid
   extend Forwardable
   extend Loggable
@@ -138,12 +139,16 @@ def storage_options
   #
   # @api private
   module GlobalDiscriminatorKeyAssignment
+
     # This class is used for obtaining the method definition location for
     # Mongoid methods.
     class InvalidFieldHost
       include Mongoid::Document
     end
 
+    # Sets the global discriminator key name.
+    #
+    # @param [ String | Symbol ] value The new discriminator key name.
     def discriminator_key=(value)
       Mongoid::Fields::Validators::Macro.validate_field_name(InvalidFieldHost, value)
       value = value.to_s

lib/mongoid/association.rb

@@ -19,6 +19,10 @@
 require 'mongoid/association/eager_loadable'
 
 module Mongoid
+
+  # Mixin module which adds association behavior to a Mongoid document.
+  # Adds methods such as #embedded? which indicate a document's
+  # relative association state.
   module Association
     extend ActiveSupport::Concern
     include Embedded::Cyclic

lib/mongoid/association/depending.rb

@@ -20,6 +20,12 @@ module Depending
       end
 
       class_methods do
+
+        # Returns all dependent association metadata objects.
+        #
+        # @return [ Array<Mongoid::Association::Relatable> ] The dependent
+        #   association metadata.
+        #
         # @api private
         def _all_dependents
           superclass_dependents = superclass.respond_to?(:_all_dependents) ? superclass._all_dependents : []
@@ -62,6 +68,14 @@ def self.define_dependency!(association)
         end
       end
 
+      # Validates that an association's dependent strategy is
+      # within the allowed enumeration.
+      #
+      # @param [ Mongoid::Association::Relatable ] association
+      #   The association to validate.
+      #
+      # @raises [ Mongoid::Errors::InvalidDependentStrategy ]
+      #   Error if invalid.
       def self.validate!(association)
         unless STRATEGIES.include?(association.dependent)
           raise Errors::InvalidDependentStrategy.new(association,

lib/mongoid/association/eager_loadable.rb

@@ -9,10 +9,19 @@ module Association
     # This module defines the eager loading behavior for criteria.
     module EagerLoadable
 
+      # Indicates whether the criteria has association
+      # inclusions which should be eager loaded.
+      #
+      # @return [ true | false ] Whether to eager load.
       def eager_loadable?
         !criteria.inclusions.empty?
       end
 
+      # Load the associations for the given documents.
+      #
+      # @param [ Array<Mongoid::Document> ] docs The documents.
+      #
+      # @return [ Array<Mongoid::Document> ] The given documents.
       def eager_load(docs)
         docs.tap do |d|
           if eager_loadable?
@@ -23,11 +32,11 @@ def eager_load(docs)
 
       # Load the associations for the given documents. This will be done
       # recursively to load the associations of the given documents'
-      # subdocuments.
+      # associated documents.
       #
       # @param [ Array<Mongoid::Association::Relatable> ] associations
       #   The associations to load.
-      # @param [ Array<Document> ] document The documents.
+      # @param [ Array<Mongoid::Document> ] docs The documents.
       def preload(associations, docs)
         assoc_map = associations.group_by(&:inverse_class_name)
         docs_map = {}

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

@@ -4,7 +4,12 @@ module Mongoid
   module Association
     module Embedded
       class EmbeddedIn
-        # Proxy class for representing :embedded_in associations.
+        # Transparent proxy for embedded_in associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the child document. This
+        # class inherits from Mongoid::Association::Proxy and forwards
+        # most of its methods to the target of the association, i.e.
+        # the parent document.
         class Proxy < Association::One
           # Instantiate a new embedded_in association.
           #

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

@@ -6,7 +6,12 @@ module Mongoid
   module Association
     module Embedded
       class EmbedsMany
-        # Proxy class for the :embeds_many association.
+        # Transparent proxy for embeds_many associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the parent document. This
+        # class inherits from Mongoid::Association::Proxy and forwards
+        # most of its methods to the target of the association, i.e.
+        # the array of child documents.
         class Proxy < Association::Many
           include Batchable
 

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

@@ -4,7 +4,12 @@ module Mongoid
   module Association
     module Embedded
       class EmbedsOne
-        # Proxy class for :embeds_one associations.
+        # Transparent proxy for embeds_one associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the parent document. This
+        # class inherits from Mongoid::Association::Proxy and forwards
+        # most of its methods to the target of the association, i.e.
+        # the child document.
         class Proxy < Association::One
           # The valid options when defining this association.
           #

lib/mongoid/association/marshalable.rb

@@ -3,6 +3,9 @@
 
 module Mongoid
   module Association
+
+    # Mixin module for Mongoid::Association::Proxy which adds
+    # custom Marshal.dump functionality.
     module Marshalable
 
       # Provides the data needed to Marshal.dump an association proxy.

lib/mongoid/association/nested/many.rb

@@ -4,6 +4,9 @@
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on many-to-n associations.
       class Many
         include Buildable
 

lib/mongoid/association/nested/nested_buildable.rb

@@ -4,6 +4,10 @@
 module Mongoid
   module Association
     module Nested
+
+      # Mixin module containing common functionality used to
+      # perform #accepts_nested_attributes_for attribute assignment
+      # on associations.
       module Buildable
 
         attr_accessor :attributes, :existing, :association, :options