Add documentation for query_methods bang methods

1 files changed, 20 insertions, 1 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 136e5778f6..c057a684e6 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -67,6 +67,7 @@ module ActiveRecord
       args.empty? ? self : spawn.includes!(*args)
     end
 
+    # Like #includes, but modifies the relation in place.
     def includes!(*args)
       args.reject! {|a| a.blank? }
 
@@ -84,6 +85,8 @@ module ActiveRecord
       args.blank? ? self : spawn.eager_load!(*args)
     end
 
+    # Like #eager_load, but modifies relation in place.
+    # object.
     def eager_load!(*args)
       self.eager_load_values += args
       self
@@ -97,6 +100,7 @@ module ActiveRecord
       args.blank? ? self : spawn.preload!(*args)
     end
 
+    # Like #preload, but modifies relation in place.
     def preload!(*args)
       self.preload_values += args
       self
@@ -114,6 +118,7 @@ module ActiveRecord
       args.blank? ? self : spawn.references!(*args)
     end
 
+    # Like #references, but modifies relation in place.
     def references!(*args)
       args.flatten!
 
@@ -158,6 +163,7 @@ module ActiveRecord
       end
     end
 
+    # Like #select, but modifies relation in place.
     def select!(value)
       self.select_values += Array.wrap(value)
       self
@@ -179,6 +185,7 @@ module ActiveRecord
       args.blank? ? self : spawn.group!(*args)
     end
 
+    # Like #group, but modifies relation in place.
     def group!(*args)
       args.flatten!
 
@@ -200,6 +207,7 @@ module ActiveRecord
       args.blank? ? self : spawn.order!(*args)
     end
 
+    # Like #order, but modifies relation in place.
     def order!(*args)
       args.flatten!
 
@@ -224,6 +232,7 @@ module ActiveRecord
       args.blank? ? self : spawn.reorder!(*args)
     end
 
+    # Like #reorder, but modifies relation in place.
     def reorder!(*args)
       args.flatten!
 
@@ -240,6 +249,7 @@ module ActiveRecord
       args.compact.blank? ? self : spawn.joins!(*args)
     end
 
+    # Like #joins, but modifies relation in place.
     def joins!(*args)
       args.flatten!
 
@@ -367,6 +377,7 @@ module ActiveRecord
       opts.blank? ? self : spawn.having!(opts, *rest)
     end
 
+    # Like #having, but modifies relation in place.
     def having!(opts, *rest)
       references!(PredicateBuilder.references(opts)) if Hash === opts
 
@@ -383,6 +394,7 @@ module ActiveRecord
       spawn.limit!(value)
     end
 
+    # Like #limit, but modifies relation in place.
     def limit!(value)
       self.limit_value = value
       self
@@ -399,17 +411,19 @@ module ActiveRecord
       spawn.offset!(value)
     end
 
+    # Like #offset, but modifies relation in place.
     def offset!(value)
       self.offset_value = value
       self
     end
 
     # Specifies locking settings (default to +true+). For more information
-    # on locking, please see +ActiveRecord::Lockin+g.
+    # on locking, please see +ActiveRecord::Locking+.
     def lock(locks = true)
       spawn.lock!(locks)
     end
 
+    # Like #lock, but modifies relation in place.
     def lock!(locks = true)
       case locks
       when String, TrueClass, NilClass
@@ -464,6 +478,7 @@ module ActiveRecord
       spawn.readonly!(value)
     end
 
+    # Like #readonly, but modifies relation in place.
     def readonly!(value = true)
       self.readonly_value = value
       self
@@ -513,6 +528,7 @@ module ActiveRecord
       spawn.from!(value, subquery_name)
     end
 
+    # Like #from, but modifies relation in place.
     def from!(value, subquery_name = nil)
       self.from_value = [value, subquery_name]
       self
@@ -532,6 +548,7 @@ module ActiveRecord
       spawn.uniq!(value)
     end
 
+    # Like #uniq, but modifies relation in place.
     def uniq!(value = true)
       self.uniq_value = value
       self
@@ -581,6 +598,7 @@ module ActiveRecord
       end
     end
 
+    # Like #extending, but modifies relation in place.
     def extending!(*modules, &block)
       modules << Module.new(&block) if block_given?
 
@@ -597,6 +615,7 @@ module ActiveRecord
       spawn.reverse_order!
     end
 
+    # Like #reverse_order, but modifies relation in place.
     def reverse_order!
       self.reverse_order_value = !reverse_order_value
       self