MONGOID-3834 Document association availability in custom getters and setters (#5503)

* MONGOID-3834 Document association availability in custom getters and setters

* add callbacks note

Author: neilshweky

source/reference/callbacks.txt

@@ -1,3 +1,5 @@
+.. _callbacks:
+
 *********
 Callbacks
 *********
@@ -59,13 +61,13 @@ for cross-cutting concerns, like queueing up background jobs.
      field :name, type: String
      field :body, type: String
      field :slug, type: String
-   
+
      before_create :send_message
-   
+
      after_save do |document|
        # Handle callback here.
      end
-   
+
      protected
      def send_message
        # Message sending code here.
@@ -80,7 +82,7 @@ syntax as well:
    class Article
      include Mongoid::Document
      field :name, type: String
-  
+
      set_callback(:create, :before) do |document|
        # Message sending code here.
      end
@@ -109,10 +111,10 @@ callback. Example:
 
    class Person
      include Mongoid::Document
-   
+
      has_many :posts, after_add: :send_email_to_subscribers
    end
-   
+
    def send_email_to_subscribers(post)
      Notifications.new_post(post).deliver
    end

source/reference/crud.txt

@@ -749,6 +749,15 @@ write the values directly into the attributes hash:
   person.attributes
   # => {"_id"=>BSON::ObjectId('606477dc2c97a628cf47075b'), "fn"=>"Artem"}
 
+.. note::
+
+  The custom setters are called during the assignment of
+  :ref:`nested attributes <nested-attributes>`, however they are called before
+  the associations are set up. Because of this, associations may not always
+  be available during these methods, and it is encouraged to include checks
+  for their presence whenever referring to them. :ref:`Callbacks <callbacks>`
+  can also be used to perform operations on certain events, and associations
+  will have already been setup and are available during their execution.
 
 .. _read-write-attribute:
 

source/reference/nested-attributes.txt

@@ -1,3 +1,5 @@
+.. _nested-attributes:
+
 *****************
 Nested Attributes
 *****************