Add documentation caveat about when to use count_by_sql. Closes #8090. [fearoffish]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6685 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 9 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 87bd064e49..bb3c58067d 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -530,6 +530,15 @@ module ActiveRecord #:nodoc:
       end
 
       # Returns the result of an SQL statement that should only include a COUNT(*) in the SELECT part.
+      # The use of this method should be restricted to complicated SQL queries that can't be executed 
+      # using the ActiveRecord::Calculations class methods.  Look into those before using this.
+      #
+      # ==== Options
+      # 
+      # +sql+: An SQL statement which should return a count query from the database, see the example below
+      #
+      # ==== Examples
+      #
       #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
       def count_by_sql(sql)
         sql = sanitize_conditions(sql)