Updated documentation here and there

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

activerecord/lib/active_record/associations.rb

@@ -193,10 +193,7 @@ module ClassMethods
       # * <tt>collection.clear</tt> - removes every object from the collection. This does not destroy the objects.
       # * <tt>collection.empty?</tt> - returns true if there are no associated objects.
       # * <tt>collection.size</tt> - returns the number of associated objects.
-      # * <tt>collection.find(id)</tt> - finds an associated object responding to the +id+ and that
-      #   meets the condition that it has to be associated with this object.
-      # * <tt>collection.find_all(conditions = nil, orderings = nil, limit = nil, joins = nil)</tt> - finds all associated objects responding 
-      #   criteria mentioned (like in the standard find_all) and that meets the condition that it has to be associated with this object.
+      # * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
       # * <tt>collection.build(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
       #   with +attributes+ and linked to this object through a foreign key but has not yet been saved. *Note:* This only works if an 
       #   associated object already exists, not if its nil!
@@ -205,14 +202,13 @@ module ClassMethods
       #   *Note:* This only works if an associated object already exists, not if its nil!
       #
       # Example: A Firm class declares <tt>has_many :clients</tt>, which will add:
-      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find_all "firm_id = #{id}"</tt>)
+      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>)
       # * <tt>Firm#clients<<</tt>
       # * <tt>Firm#clients.delete</tt>
       # * <tt>Firm#clients.clear</tt>
       # * <tt>Firm#clients.empty?</tt> (similar to <tt>firm.clients.size == 0</tt>)
       # * <tt>Firm#clients.size</tt> (similar to <tt>Client.count "firm_id = #{id}"</tt>)
-      # * <tt>Firm#clients.find</tt> (similar to <tt>Client.find_on_conditions(id, "firm_id = #{id}")</tt>)
-      # * <tt>Firm#clients.find_all</tt> (similar to <tt>Client.find_all "firm_id = #{id}"</tt>)
+      # * <tt>Firm#clients.find</tt> (similar to <tt>Client.find(id, :conditions => "firm_id = #{id}")</tt>)
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("client_id" => id); c.save; c</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.

activerecord/lib/active_record/associations/has_many_association.rb

@@ -20,6 +20,7 @@ def build(attributes = {})
         end
       end
 
+      # DEPRECATED.
       def find_all(runtime_conditions = nil, orderings = nil, limit = nil, joins = nil)
         if @options[:finder_sql]
           records = @association_class.find_by_sql(@finder_sql)
@@ -31,6 +32,11 @@ def find_all(runtime_conditions = nil, orderings = nil, limit = nil, joins = nil
         end
       end
 
+      # DEPRECATED. Find the first associated record.  All arguments are optional.
+      def find_first(conditions = nil, orderings = nil)
+        find_all(conditions, orderings, 1).first
+      end
+
       # Count the number of associated records. All arguments are optional.
       def count(runtime_conditions = nil)
         if @options[:counter_sql]
@@ -43,11 +49,6 @@ def count(runtime_conditions = nil)
           @association_class.count(sql)
         end
       end
-      
-      # Find the first associated record.  All arguments are optional.
-      def find_first(conditions = nil, orderings = nil)
-        find_all(conditions, orderings, 1).first
-      end
 
       def find(*args)
         options = Base.send(:extract_options_from_args!, args)

activerecord/test/associations_test.rb

@@ -317,8 +317,8 @@ def test_find_ids
   def test_find_all
     firm = Firm.find_first
     assert_equal firm.clients, firm.clients.find_all
-    assert_equal 2, firm.clients.find_all("type = 'Client'").length
-    assert_equal 1, firm.clients.find_all("name = 'Summit'").length
+    assert_equal 2, firm.clients.find(:all, :conditions => "type = 'Client'").length
+    assert_equal 1, firm.clients.find(:all, :conditions => "name = 'Summit'").length
   end
 
   def test_find_all_sanitized
@@ -682,7 +682,7 @@ def test_forgetting_the_load_when_foreign_key_enters_late
 
   def test_field_name_same_as_foreign_key
     computer = Computer.find 1
-    assert_not_nil computer.developer, ":foreign key == attribute didn't lock up"
+    assert_not_nil computer.developer, ":foreign key == attribute didn't lock up" # '
   end
 
   def xtest_counter_cache
@@ -705,12 +705,7 @@ def xtest_counter_cache
 
 
 class HasAndBelongsToManyAssociationsTest < Test::Unit::TestCase
-  def setup
-    @accounts, @companies, @developers, @projects, @developers_projects = 
-      create_fixtures "accounts", "companies", "developers", "projects", "developers_projects"
-
-    @signals37 = Firm.find(1)
-  end
+  fixtures :accounts, :companies, :developers, :projects, :developers_projects
   
   def test_has_and_belongs_to_many
     david = Developer.find(1)
@@ -914,4 +909,12 @@ def test_find_in_association
     @active_record.developers.reload
     assert_equal @developers["david"].find, @active_record.developers.find(@developers["david"]["id"]), "Ruby find"
   end
-end
+
+  def xtest_find_in_association_with_options
+    developers = @active_record.developers.find(:all)
+    assert_equal 2, developers.size
+    
+    assert_equal @david, @active_record.developers.find(:first, :conditions => "salary < 10000")
+    assert_equal @jamis, @active_record.developers.find(:first, :order => "salary DESC")
+  end
+end
\ No newline at end of file