Skip to content
This repository
Browse code

Updated documentation for associations #387 [canadaduane]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@299 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit cab24945634bc22b0c0c5d10b72c83eaa09f1e41 1 parent 3b05d41
David Heinemeier Hansson authored
17  activerecord/lib/active_record/associations.rb
@@ -122,7 +122,7 @@ def clear_association_cache #:nodoc:
122 122
     # All of the association macros can be specialized through options which makes more complex cases than the simple and guessable ones
123 123
     # possible.
124 124
     module ClassMethods
125  
-      # Adds the following methods for retrival and query of collections of associated objects.
  125
+      # Adds the following methods for retrieval and query of collections of associated objects.
126 126
       # +collection+ is replaced with the symbol passed as the first argument, so 
127 127
       # <tt>has_many :clients</tt> would add among others <tt>has_clients?</tt>.
128 128
       # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects.
@@ -224,7 +224,7 @@ def has_many(association_id, options = {})
224 224
         deprecated_build_method(association_name)
225 225
       end
226 226
 
227  
-      # Adds the following methods for retrival and query of a single associated object.
  227
+      # Adds the following methods for retrieval and query of a single associated object.
228 228
       # +association+ is replaced with the symbol passed as the first argument, so 
229 229
       # <tt>has_one :manager</tt> would add among others <tt>has_manager?</tt>.
230 230
       # * <tt>association(force_reload = false)</tt> - returns the associated object. Nil is returned if none is found.
@@ -280,7 +280,7 @@ def has_one(association_id, options = {})
280 280
         module_eval "before_destroy '#{association_name}.destroy if has_#{association_name}?'" if options[:dependent]
281 281
       end
282 282
 
283  
-      # Adds the following methods for retrival and query for a single associated object that this object holds an id to.
  283
+      # Adds the following methods for retrieval and query for a single associated object that this object holds an id to.
284 284
       # +association+ is replaced with the symbol passed as the first argument, so 
285 285
       # <tt>belongs_to :author</tt> would add among others <tt>has_author?</tt>.
286 286
       # * <tt>association(force_reload = false)</tt> - returns the associated object. Nil is returned if none is found.
@@ -289,7 +289,7 @@ def has_one(association_id, options = {})
289 289
       #   same id as the associated object.
290 290
       # * <tt>association.nil?</tt> - returns true if there is no associated object.
291 291
       #
292  
-      # Example: An Post class declares <tt>has_one :author</tt>, which will add:
  292
+      # Example: A Post class declares <tt>has_one :author</tt>, which will add:
293 293
       # * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)
294 294
       # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
295 295
       # * <tt>Post#author?</tt> (similar to <tt>post.author == some_author</tt>)
@@ -364,9 +364,12 @@ def belongs_to(association_id, options = {})
364 364
       #
365 365
       # Any additional fields added to the join table will be placed as attributes when pulling records out through
366 366
       # has_and_belongs_to_many associations. This is helpful when have information about the association itself
367  
-      # that you want available on retrival.
  367
+      # that you want available on retrieval. Note that any fields in the join table will override matching field names
  368
+      # in the two joined tables. As a consequence, having an "id" field in the join table usually has the undesirable
  369
+      # result of clobbering the "id" fields in either of the other two tables.
  370
+      # 
368 371
       #
369  
-      # Adds the following methods for retrival and query.
  372
+      # Adds the following methods for retrieval and query.
370 373
       # +collection+ is replaced with the symbol passed as the first argument, so 
371 374
       # <tt>has_and_belongs_to_many :categories</tt> would add among others +add_categories+.
372 375
       # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects.
@@ -574,4 +577,4 @@ def require_association_class(class_name)
574 577
         end
575 578
     end
576 579
   end
577  
-end
  580
+end

0 notes on commit cab2494

Please sign in to comment.
Something went wrong with that request. Please try again.