Document API for exists?'s parameter and provide examples of usage. C…

…loses rails#7913 [fearoffish]

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

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Document API for exists?'s parameter and provide examples of usage. Closes #7913 [fearoffish]
+
 * Document API for create's attributes parameter and provide examples. Closes #7915 [fearoffish]
 
 * Documentation for find incorrectly omits the :conditions option from various examples. Closes #7923 [mattwestcott]

activerecord/lib/active_record/base.rb

@@ -461,9 +461,18 @@ def find_by_sql(sql)
         connection.select_all(sanitize_sql(sql), "#{name} Load").collect! { |record| instantiate(record) }
       end
 
-      # Returns true if the given +id+ represents the primary key of a record in the database, false otherwise.
-      # You can also pass a set of SQL conditions. 
-      # Example:
+      # Checks whether a record exists in the database that matches conditions given.  These conditions 
+      # can either be a single integer representing a primary key id to be found, or a condition to be 
+      # matched like using ActiveRecord#find.
+      #
+      # The +id_or_conditions+ parameter can be an Integer or a String if you want to search the primary key 
+      # column of the table for a matching id, or if you're looking to match against a condition you can use 
+      # an Array or a Hash.
+      #
+      # Possible gotcha: You can't pass in a condition as a string e.g. "name = 'Jamie'", this would be 
+      # sanitized and then queried against the primary key column as "id = 'name = \'Jamie"
+      #
+      # ==== Examples
       #   Person.exists?(5)
       #   Person.exists?('5')
       #   Person.exists?(:name => "David")