MONGOID-5291 Clarify whether :touch option is applicable for all updates (#5481)

Author: neilshweky

docs/reference/associations.txt

@@ -1396,19 +1396,21 @@ Mongoid to instantiate a new document when the association is accessed and it is
 
 Touching
 --------
-
 Any ``belongs_to`` association can take an optional ``:touch`` option which
-will cause the parent document be touched whenever the child document is
-touched:
+will cause the parent document to be touched whenever the child document is
+updated:
 
 .. code-block:: ruby
 
   class Band
     include Mongoid::Document
+    field :name
     belongs_to :label, touch: true
   end
 
   band = Band.first
+  band.name = "The Rolling Stones"
+  band.save! # Calls touch on the parent label.
   band.touch # Calls touch on the parent label.
 
 ``:touch`` can also take a string or symbol argument specifying a field to

spec/mongoid/touchable_spec.rb

@@ -587,7 +587,7 @@
 
     context "when the touch option is true" do
 
-      shared_examples "updates the updated_at" do
+      shared_examples "updates the parent's updated_at" do
 
         let!(:start_time) { Timecop.freeze(Time.at(Time.now.to_i)) }
 
@@ -624,19 +624,58 @@
         end
       end
 
+      shared_examples "updates the child's updated_at" do
+
+        let!(:start_time) { Timecop.freeze(Time.at(Time.now.to_i)) }
+
+        let(:update_time) do
+          Timecop.freeze(Time.at(Time.now.to_i) + 2)
+        end
+
+        after do
+          Timecop.return
+        end
+
+        let(:building) do
+          parent_cls.create!
+        end
+
+        let(:floor) do
+          building.floors.create!
+        end
+
+        before do
+          floor
+          update_time
+          floor.level = 9
+          floor.send(meth)
+        end
+
+        it "the parent is not nil" do
+          expect(floor.building).to_not be nil
+        end
+
+        it "updates the child's timestamp" do
+          floor.updated_at.should == update_time
+          floor.reload.updated_at.should == update_time
+        end
+      end
+
       [ :save!, :destroy, :touch].each do |meth|
         context "with #{meth} on referenced associations" do
           let(:parent_cls) { TouchableSpec::Referenced::Building }
           let(:meth) { meth }
 
-          include_examples "updates the updated_at"
+          include_examples "updates the child's updated_at" unless meth == :destroy
+          include_examples "updates the parent's updated_at"
         end
 
         context "with #{meth} on embedded associations" do
           let(:parent_cls) { TouchableSpec::Embedded::Building }
           let(:meth) { meth }
 
-          include_examples "updates the updated_at"
+          include_examples "updates the child's updated_at" unless meth == :destroy
+          include_examples "updates the parent's updated_at"
         end
       end
     end