MONGOID-5205 Document reloading behavior for changed attributes (#5150)

* revise existing reloading docs

* reloading behavior when not found does not raise

* test reloading without raising on not found

* document referenced associations

* test referenced associations

* use a different model

Co-authored-by: Oleg Pudeyev <code@olegp.name>

Author: p-mongo

source/reference/crud.txt

@@ -549,31 +549,68 @@ Reloading
 =========
 
 Use the ``reload`` method to fetch the most recent version of a document from
-the database:
+the database. Any unsaved modifications to the document's attributes are lost:
 
 .. code-block:: ruby
 
-  band = Band.find(..)
+  band = Band.create!(name: 'foo')
+  # => #<Band _id: 6206d06de1b8324561f179c9, name: "foo", description: nil, likes: nil>
+
+  band.name = 'bar'
+  band
+  # => #<Band _id: 6206d06de1b8324561f179c9, name: "bar", description: nil, likes: nil>
+
   band.reload
+  # => #<Band _id: 6206d06de1b8324561f179c9, name: "foo", description: nil, likes: nil>
+
+When a document is reloaded, all of its embedded associations are also reloaded
+in the same query (since embedded documents are stored in the parent document
+on the server). If a document has referenced associations, the loaded
+associations' are not reloaded but their values are cleared, such that these
+associations would be loaded from the database at the next access.
 
 If the model has a :ref:`shard key <shard-keys>` defined, the shard key value
 is included in the reloading query.
 
-.. note::
+If the database does not contain a matching document, Mongoid normally raises
+``Mongoid::Errors::DocumentNotFound``. However, if the configuration option
+``raise_not_found_error`` is set to ``false``, and the database does not
+contain a matching document, Mongoid replaces the current document with a newly
+created document whose attributes are set to default values. Importantly, this
+generally causes the ``_id`` of the document to change, as the following
+example demonstrates:
 
-  ``reload`` also works when the document has not been persisted, in which case
-  it performs a query using the ``id`` value (and shard key value, if a shard
-  key is defined):
+.. code-block:: ruby
 
-  .. code-block:: ruby
+  band = Band.create!
+  # => #<Band _id: 6206d00de1b8324561f179c7, name: "foo", description: nil, likes: nil>
 
-    existing = Band.create!(name: 'Photek')
-    
-    # Unsaved document
-    band = Band.new(id: existing.id)
-    band.reload
-    band.name
-    # => "Photek"
+  Mongoid.raise_not_found_error = false
+  band.destroy
+  
+  band.reload
+  # => #<Band _id: 6206d031e1b8324561f179c8, name: nil, description: nil, likes: nil>
+
+For this reason, it is not recommended to use ``reload`` when
+``raise_not_found_error`` is set to ``false``.
+
+
+Reloading Unsaved Documents
+---------------------------
+
+``reload`` can be called when the document has not yet been persisted.
+In this case ``reload`` performs a ``find`` query using the ``id`` value
+specified in the document (and the shard key value, if a shard key is defined):
+
+.. code-block:: ruby
+
+  existing = Band.create!(name: 'Photek')
+  
+  # Unsaved document
+  band = Band.new(id: existing.id)
+  band.reload
+  band.name
+  # => "Photek"
 
 
 Accessing Field Values