add explanation of raising errors when a limit scope is supplied in Relation#delete_all

activerecord/lib/active_record/relation.rb

@@ -370,17 +370,12 @@ def destroy(id)
       end
     end
 
-    # Deletes the records matching +conditions+ without instantiating the records first, and hence not
-    # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that
-    # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations
-    # though, in particular <tt>:dependent</tt> rules defined on associations are not honored. Returns
-    # the number of rows affected.
-    #
-    # ==== Parameters
-    #
-    # * +conditions+ - Conditions are specified the same way as with +find+ method.
-    #
-    # ==== Example
+    # Deletes the records matching +conditions+ without instantiating the records
+    # first, and hence not calling the +destroy+ method nor invoking callbacks. This
+    # is a single SQL DELETE statement that goes straight to the database, much more
+    # efficient than +destroy_all+. Be careful with relations though, in particular
+    # <tt>:dependent</tt> rules defined on associations are not honored. Returns the
+    # number of rows affected.
     #
     #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
     #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
@@ -389,6 +384,11 @@ def destroy(id)
     # Both calls delete the affected posts all at once with a single DELETE statement.
     # If you need to destroy dependent associations or call your <tt>before_*</tt> or
     # +after_destroy+ callbacks, use the +destroy_all+ method instead.
+    #
+    # If a limit scope is supplied, +delete_all+ raises an ActiveRecord error:
+    #
+    #   Post.limit(100).delete_all
+    #   # => ActiveRecord::ActiveRecordError: delete_all doesn't support limit scope
     def delete_all(conditions = nil)
       raise ActiveRecordError.new("delete_all doesn't support limit scope") if self.limit_value