Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #8899: doc_grammar_fixes_for_associations3.2.diff

File doc_grammar_fixes_for_associations3.2.diff, 70.6 kB (added by seanhussey, 1 year ago)

Updated to fix conflict with [7236]

  • activerecord/lib/active_record/callbacks.rb

    old new  
    11require 'observer' 
    22 
    33module ActiveRecord 
    4   # Callbacks are hooks into the lifecycle of an Active Record object that allows you to trigger logic 
     4  # Callbacks are hooks into the lifecycle of an Active Record object that allow you to trigger logic 
    55  # before or after an alteration of the object state. This can be used to make sure that associated and 
    6   # dependent objects are deleted when destroy is called (by overwriting before_destroy) or to massage attributes 
    7   # before they're validated (by overwriting before_validation). As an example of the callbacks initiated, consider 
    8   # the Base#save call: 
     6  # dependent objects are deleted when destroy is called (by overwriting +before_destroy+) or to massage attributes 
     7  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider 
     8  # the <tt>Base#save</tt> call: 
    99  # 
    10   # * (-) save 
    11   # * (-) valid? 
    12   # * (1) before_validation 
    13   # * (2) before_validation_on_create 
    14   # * (-) validate 
    15   # * (-) validate_on_create 
    16   # * (3) after_validation 
    17   # * (4) after_validation_on_create 
    18   # * (5) before_save 
    19   # * (6) before_create 
    20   # * (-) create 
    21   # * (7) after_create 
    22   # * (8) after_save 
     10  # * (-) <tt>save</tt> 
     11  # * (-) <tt>valid</tt> 
     12  # * (1) <tt>before_validation</tt> 
     13  # * (2) <tt>before_validation_on_create</tt> 
     14  # * (-) <tt>validate</tt> 
     15  # * (-) <tt>validate_on_create</tt> 
     16  # * (3) <tt>after_validation</tt> 
     17  # * (4) <tt>after_validation_on_create</tt> 
     18  # * (5) <tt>before_save</tt> 
     19  # * (6) <tt>before_create</tt> 
     20  # * (-) <tt>create</tt> 
     21  # * (7) <tt>after_create</tt> 
     22  # * (8) <tt>after_save</tt> 
    2323  # 
    2424  # That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the 
    2525  # Active Record lifecycle. 
    …… 
    6262  #     before_destroy :destroy_readers 
    6363  #   end 
    6464  # 
    65   # Now, when Topic#destroy is run only +destroy_author+ is called. When Reply#destroy is run both +destroy_author+ and 
    66   # +destroy_readers+ is called. Contrast this to the situation where we've implemented the save behavior through overwriteable 
     65  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is run, both +destroy_author+ and 
     66  # +destroy_readers+ are called. Contrast this to the situation where we've implemented the save behavior through overwriteable 
    6767  # methods: 
    6868  # 
    6969  #   class Topic < ActiveRecord::Base 
    …… 
    7474  #     def before_destroy() destroy_readers end 
    7575  #   end 
    7676  # 
    77   # In that case, Reply#destroy would only run +destroy_readers+ and _not_ +destroy_author+. So use the callback macros when 
    78   # you want to ensure that a certain callback is called for the entire hierarchy and the regular overwriteable methods when you 
    79   # want to leave it up to each descendent to decide whether they want to call +super+ and trigger the inherited callbacks. 
     77  # In that case, <tt>Reply#destroy</tt> would only run +destroy_readers+ and _not_ +destroy_author+. So, use the callback macros when 
     78  # you want to ensure that a certain callback is called for the entire hierarchy, and use the regular overwriteable methods 
     79  # when you want to leave it up to each descendent to decide whether they want to call +super+ and trigger the inherited callbacks. 
    8080  # 
    8181  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the callbacks before specifying the 
    8282  # associations. Otherwise, you might trigger the loading of a child before the parent has registered the callbacks and they won't 
    …… 
    143143  #     before_destroy 'self.class.delete_all "parent_id = #{id}"' 
    144144  #   end 
    145145  # 
    146   # Notice that single plings (') are used so the #{id} part isn't evaluated until the callback is triggered. Also note that these 
     146  # Notice that single plings (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback is triggered. Also note that these 
    147147  # inline callbacks can be stacked just like the regular ones: 
    148148  # 
    149149  #   class Topic < ActiveRecord::Base 
    …… 
    151151  #                    'puts "Evaluated after parents are destroyed"' 
    152152  #   end 
    153153  # 
    154   # == The after_find and after_initialize exceptions 
     154  # == The +after_find+ and +after_initialize+ exceptions 
    155155  # 
    156   # Because after_find and after_initialize are called for each object found and instantiated by a finder, such as Base.find(:all), we've had 
    157   # to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_find and 
    158   # after_initialize will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the 
     156  # Because +after_find+ and +after_initialize+ are called for each object found and instantiated by a finder, such as <tt>Base.find(:all)</tt>, we've had 
     157  # to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, +after_find+ and 
     158  # +after_initialize+ will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the 
    159159  # callback types will be called. 
    160160  # 
    161   # == before_validation* returning statements 
     161  # == <tt>before_validation*</tt> returning statements 
    162162  # 
    163   # If the returning value of a before_validation callback can be evaluated to false, the process will be aborted and Base#save will return false. 
    164   # If Base#save! is called it will raise a RecordNotSave error. 
     163  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+. 
     164  # If <tt>Base#save!</tt> is called it will raise a +RecordNotSave+ exception. 
    165165  # Nothing will be appended to the errors object. 
    166166  # 
    167167  # == Cancelling callbacks 
    168168  # 
    169   # If a before_* callback returns false, all the later callbacks and the associated action are cancelled. If an after_* callback returns 
    170   # false, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks 
     169  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are cancelled. If an <tt>after_*</tt> callback returns 
     170  # +false+, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks 
    171171  # defined as methods on the model, which are called last. 
    172172  module Callbacks 
    173173    CALLBACKS = %w( 
    …… 
    215215      end 
    216216    end 
    217217 
    218     # Is called when the object was instantiated by one of the finders, like Base.find. 
     218    # Is called when the object was instantiated by one of the finders, like <tt>Base.find</tt>. 
    219219    #def after_find() end 
    220220 
    221     # Is called after the object has been instantiated by a call to Base.new. 
     221    # Is called after the object has been instantiated by a call to <tt>Base.new</tt>. 
    222222    #def after_initialize() end 
    223223 
    224224    def initialize_with_callbacks(attributes = nil) #:nodoc: 
    …… 
    229229    end 
    230230    private :initialize_with_callbacks 
    231231 
    232     # Is called _before_ Base.save (regardless of whether it's a create or update save). 
     232    # Is called _before_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save). 
    233233    def before_save() end 
    234234 
    235     # Is called _after_ Base.save (regardless of whether it's a create or update save). 
     235    # Is called _after_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save). 
    236236    # 
    237237    #  class Contact < ActiveRecord::Base 
    238238    #    after_save { logger.info( 'New contact saved!' ) } 
    …… 
    246246    end 
    247247    private :create_or_update_with_callbacks 
    248248 
    249     # Is called _before_ Base.save on new objects that haven't been saved yet (no record exists). 
     249    # Is called _before_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists). 
    250250    def before_create() end 
    251251 
    252     # Is called _after_ Base.save on new objects that haven't been saved yet (no record exists). 
     252    # Is called _after_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists). 
    253253    def after_create() end 
    254254    def create_with_callbacks #:nodoc: 
    255255      return false if callback(:before_create) == false 
    …… 
    259259    end 
    260260    private :create_with_callbacks 
    261261 
    262     # Is called _before_ Base.save on existing objects that have a record. 
     262    # Is called _before_ <tt>Base.save</tt> on existing objects that have a record. 
    263263    def before_update() end 
    264264 
    265     # Is called _after_ Base.save on existing objects that have a record. 
     265    # Is called _after_ <tt>Base.save</tt> on existing objects that have a record. 
    266266    def after_update() end 
    267267 
    268268    def update_with_callbacks #:nodoc: 
    …… 
    273273    end 
    274274    private :update_with_callbacks 
    275275 
    276     # Is called _before_ Validations.validate (which is part of the Base.save call). 
     276    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call). 
    277277    def before_validation() end 
    278278 
    279     # Is called _after_ Validations.validate (which is part of the Base.save call). 
     279    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call). 
    280280    def after_validation() end 
    281281 
    282     # Is called _before_ Validations.validate (which is part of the Base.save call) on new objects 
     282    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects 
    283283    # that haven't been saved yet (no record exists). 
    284284    def before_validation_on_create() end 
    285285 
    286     # Is called _after_ Validations.validate (which is part of the Base.save call) on new objects 
     286    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects 
    287287    # that haven't been saved yet (no record exists). 
    288288    def after_validation_on_create()  end 
    289289 
    290     # Is called _before_ Validations.validate (which is part of the Base.save call) on 
     290    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on 
    291291    # existing objects that have a record. 
    292292    def before_validation_on_update() end 
    293293 
    294     # Is called _after_ Validations.validate (which is part of the Base.save call) on 
     294    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on 
    295295    # existing objects that have a record. 
    296296    def after_validation_on_update()  end 
    297297 
    …… 
    308308      return result 
    309309    end 
    310310 
    311     # Is called _before_ Base.destroy. 
     311    # Is called _before_ <tt>Base.destroy</tt>. 
    312312    # 
    313313    # Note: If you need to _destroy_ or _nullify_ associated records first, 
    314     # use the _:dependent_ option on your associations. 
     314    # use the <tt>:dependent</tt> option on your associations. 
    315315    def before_destroy() end 
    316316 
    317     # Is called _after_ Base.destroy (and all the attributes have been frozen). 
     317    # Is called _after_ <tt>Base.destroy</tt> (and all the attributes have been frozen). 
    318318    # 
    319319    #  class Contact < ActiveRecord::Base 
    320320    #    after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) } 

  • activerecord/lib/active_record/associations/association_proxy.rb

    old new  
    139139        end 
    140140 
    141141        # Can be overwritten by associations that might have the foreign key available for an association without 
    142         # having the object itself (and still being a new record). Currently, only belongs_to present this scenario. 
     142        # having the object itself (and still being a new record). Currently, only belongs_to presents this scenario. 
    143143        def foreign_key_present 
    144144          false 
    145145        end 

  • activerecord/lib/active_record/associations/association_collection.rb

    old new  
    6565 
    6666      # Removes all records from this association.  Returns +self+ so method calls may be chained. 
    6767      def clear 
    68         return self if length.zero? # forces load_target if hasn't happened already 
     68        return self if length.zero? # forces load_target if it hasn't happened already 
    6969 
    7070        if @reflection.options[:dependent] && @reflection.options[:dependent] == :delete_all 
    7171          destroy_all 

  • activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb

    old new  
    1414      end 
    1515 
    1616      def create(attributes = {}) 
    17         # Can't use Base.create since the foreign key may be a protected attribute. 
     17        # Can't use Base.create because the foreign key may be a protected attribute. 
    1818        if attributes.is_a?(Array) 
    1919          attributes.collect { |attr| create(attr) } 
    2020        else 
    …… 
    137137        end 
    138138 
    139139        # Join tables with additional columns on top of the two foreign keys must be considered ambigious unless a select 
    140         # clause has been explicitly defined. Otherwise you can get broken records back, if, say, the join column also has 
    141         # and id column, which will then overwrite the id column of the records coming back. 
     140        # clause has been explicitly defined. Otherwise you can get broken records back, if, for example, the join column also has 
     141        # an id column. This will then overwrite the id column of the records coming back. 
    142142        def finding_with_ambigious_select?(select_clause) 
    143143          !select_clause && @owner.connection.columns(@reflection.options[:join_table], "Join Table Columns").size != 2 
    144144        end 

  • activerecord/lib/active_record/associations/has_one_association.rb

    old new  
    7676        end 
    7777 
    7878        def new_record(replace_existing) 
    79           # make sure we load the target first, if we plan on replacing the existing 
     79          # Make sure we load the target first, if we plan on replacing the existing 
    8080          # instance. Otherwise, if the target has not previously been loaded 
    8181          # elsewhere, the instance we create will get orphaned. 
    8282          load_target if replace_existing 

  • activerecord/lib/active_record/associations/has_many_through_association.rb

    old new  
    6767 
    6868      [:push, :concat].each { |method| alias_method method, :<< } 
    6969 
    70       # Remove +records+ from this association.  Does not destroy +records+. 
     70      # Removes +records+ from this association.  Does not destroy +records+. 
    7171      def delete(*records) 
    7272        records = flatten_deeper(records) 
    7373        records.each { |associate| raise_on_type_mismatch(associate) } 

  • activerecord/lib/active_record/associations.rb

    old new  
    7676     
    7777    # Associations are a set of macro-like class methods for tying objects together through foreign keys. They express relationships like  
    7878    # "Project has one Project Manager" or "Project belongs to a Portfolio". Each macro adds a number of methods to the class which are  
    79     # specialized according to the collection or association symbol and the options hash. It works much the same way as Ruby's own attr*  
     79    # specialized according to the collection or association symbol and the options hash. It works much the same way as Ruby's own <tt>attr*</tt>  
    8080    # methods. Example: 
    8181    # 
    8282    #   class Project < ActiveRecord::Base 
    …… 
    146146    #  
    147147    # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many 
    148148    # and many-to-many cardinality. Each model uses an association to describe its role in 
    149     # the relation. In each case, the belongs_to association is used in the model that has 
     149    # the relation. In each case, the +belongs_to+ association is used in the model that has 
    150150    # the foreign key. 
    151151    # 
    152152    # === One-to-one 
    153153    # 
    154     # Use has_one in the base, and belongs_to in the associated model. 
     154    # Use +has_one+ in the base, and +belongs_to+ in the associated model. 
    155155    # 
    156156    #   class Employee < ActiveRecord::Base 
    157157    #     has_one :office 
    …… 
    162162    # 
    163163    # === One-to-many 
    164164    # 
    165     # Use has_many in the base, and belongs_to in the associated model. 
     165    # Use +has_many+ in the base, and +belongs_to+ in the associated model. 
    166166    # 
    167167    #   class Manager < ActiveRecord::Base 
    168168    #     has_many :employees 
    …… 
    175175    # 
    176176    # There are two ways to build a many-to-many relationship. 
    177177    # 
    178     # The first way uses a has_many association with the :through option and a join model, so 
     178    # The first way uses a +has_many+ association with the <tt>:through</tt> option and a join model, so 
    179179    # there are two stages of associations. 
    180180    # 
    181181    #   class Assignment < ActiveRecord::Base 
    …… 
    191191    #     has_many :programmers, :through => :assignments 
    192192    #   end 
    193193    # 
    194     # For the second way, use has_and_belongs_to_many in both models. This requires a join table 
     194    # For the second way, use +has_and_belongs_to_many+ in both models. This requires a join table 
    195195    # that has no corresponding model or primary key. 
    196196    # 
    197197    #   class Programmer < ActiveRecord::Base 
    …… 
    201201    #     has_and_belongs_to_many :programmers    # foreign keys in the join table 
    202202    #   end 
    203203    # 
    204     # It is not always a simple decision which way of building a many-to-many relationship is best. 
    205     # But if you need to work with the relationship model as its own entity, then you'll need to 
    206     # use has_many :through. Use has_and_belongs_to_many when working with legacy schemas or when 
     204    # Choosing which way to build a many-to-many relationship is not always simple. 
     205    # If you need to work with the relationship model as its own entity,  
     206    # use <tt>has_many :through</tt>. Use +has_and_belongs_to_many+ when working with legacy schemas or when 
    207207    # you never work directly with the relationship itself. 
    208208    # 
    209     # == Is it a belongs_to or has_one association? 
     209    # == Is it a +belongs_to+ or +has_one+ association? 
    210210    # 
    211     # Both express a 1-1 relationship, the difference is mostly where to place the foreign key, which goes on the table for the class 
    212     # saying belongs_to. Example: 
     211    # Both express a 1-1 relationship. The difference is mostly where to place the foreign key, which goes on the table for the class 
     212    # declaring the +belongs_to+ relationship. Example: 
    213213    # 
    214214    #   class User < ActiveRecord::Base 
    215215    #     # I reference an account. 
    …… 
    243243    # 
    244244    # === One-to-one associations 
    245245    # 
    246     # * Assigning an object to a has_one association automatically saves that object and the object being replaced (if there is one), in 
    247     #   order to update their primary keys - except if the parent object is unsaved (new_record? == true). 
    248     # * If either of these saves fail (due to one of the objects being invalid) the assignment statement returns false and the assignment 
     246    # * Assigning an object to a +has_one+ association automatically saves that object and the object being replaced (if there is one), in 
     247    #   order to update their primary keys - except if the parent object is unsaved (<tt>new_record? == true</tt>). 
     248    # * If either of these saves fail (due to one of the objects being invalid) the assignment statement returns +false+ and the assignment 
    249249    #   is cancelled. 
    250     # * If you wish to assign an object to a has_one association without saving it, use the #association.build method (documented below). 
    251     # * Assigning an object to a belongs_to association does not save the object, since the foreign key field belongs on the parent. It does 
    252     #   not save the parent either. 
     250    # * If you wish to assign an object to a +has_one+ association without saving it, use the <tt>#association.build</tt> method (documented below). 
     251    # * Assigning an object to a +belongs_to+ association does not save the object, since the foreign key field belongs on the parent. It  
     252    #   does not save the parent either. 
    253253    # 
    254254    # === Collections 
    255255    # 
    256     # * Adding an object to a collection (has_many or has_and_belongs_to_many) automatically saves that object, except if the parent object 
     256    # * Adding an object to a collection (+has_many+ or +has_and_belongs_to_many+) automatically saves that object, except if the parent object 
    257257    #   (the owner of the collection) is not yet stored in the database. 
    258     # * If saving any of the objects being added to a collection (via #push or similar) fails, then #push returns false. 
    259     # * You can add an object to a collection without automatically saving it by using the #collection.build method (documented below). 
    260     # * All unsaved (new_record? == true) members of the collection are automatically saved when the parent is saved. 
     258    # * If saving any of the objects being added to a collection (via <tt>#push</tt> or similar) fails, then <tt>#push</tt> returns +false+. 
     259    # * You can add an object to a collection without automatically saving it by using the <tt>#collection.build</tt> method (documented below). 
     260    # * All unsaved (<tt>new_record? == true</tt>) members of the collection are automatically saved when the parent is saved. 
    261261    # 
    262262    # === Association callbacks 
    263263    # 
    264264    # Similiar to the normal callbacks that hook into the lifecycle of an Active Record object, you can also define callbacks that get 
    265     # trigged when you add an object to or removing an object from a association collection. Example: 
     265    # trigged when you add an object to or remove an object from an association collection. Example: 
    266266    # 
    267267    #   class Project 
    268268    #     has_and_belongs_to_many :developers, :after_add => :evaluate_velocity 
    …… 
    278278    #     has_and_belongs_to_many :developers, :after_add => [:evaluate_velocity, Proc.new { |p, d| p.shipping_date = Time.now}] 
    279279    #   end 
    280280    # 
    281     # Possible callbacks are: before_add, after_add, before_remove and after_remove. 
     281    # Possible callbacks are: +before_add+, +after_add+, +before_remove+ and +after_remove+. 
    282282    # 
    283     # Should any of the before_add callbacks throw an exception, the object does not get added to the collection. Same with 
    284     # the before_remove callbacks, if an exception is thrown the object doesn't get removed. 
     283    # Should any of the +before_add+ callbacks throw an exception, the object does not get added to the collection. Same with 
     284    # the +before_remove+ callbacks; if an exception is thrown the object doesn't get removed. 
    285285    # 
    286286    # === Association extensions 
    287287    # 
    288     # The proxy objects that controls the access to associations can be extended through anonymous modules. This is especially 
     288    # The proxy objects that control the access to associations can be extended through anonymous modules. This is especially 
    289289    # beneficial for adding new finders, creators, and other factory-type methods that are only used as part of this association. 
    290290    # Example: 
    291291    # 
    …… 
    319319    #     has_many :people, :extend => FindOrCreateByNameExtension 
    320320    #   end 
    321321    # 
    322     # If you need to use multiple named extension modules, you can specify an array of modules with the :extend option. 
     322    # If you need to use multiple named extension modules, you can specify an array of modules with the <tt>:extend</tt> option. 
    323323    # In the case of name conflicts between methods in the modules, methods in modules later in the array supercede 
    324324    # those earlier in the array. Example: 
    325325    # 
    …… 
    332332    #  
    333333    # * +proxy_owner+ - Returns the object the association is part of. 
    334334    # * +proxy_reflection+ - Returns the reflection object that describes the association. 
    335     # * +proxy_target+ - Returns the associated object for belongs_to and has_one, or the collection of associated objects for has_many and has_and_belongs_to_many. 
     335    # * +proxy_target+ - Returns the associated object for +belongs_to+ and +has_one+, or the collection of associated objects for +has_many+ and +has_and_belongs_to_many+. 
    336336    # 
    337337    # === Association Join Models 
    338338    #  
    339     # Has Many associations can be configured with the :through option to use an explicit join model to retrieve the data.  This 
    340     # operates similarly to a <tt>has_and_belongs_to_many</tt> association.  The advantage is that you're able to add validations, 
     339    # Has Many associations can be configured with the <tt>:through</tt> option to use an explicit join model to retrieve the data.  This 
     340    # operates similarly to a +has_and_belongs_to_many+ association.  The advantage is that you're able to add validations, 
    341341    # callbacks, and extra attributes on the join model.  Consider the following schema: 
    342342    #  
    343343    #   class Author < ActiveRecord::Base 
    …… 
    354354    #   @author.authorships.collect { |a| a.book } # selects all books that the author's authorships belong to. 
    355355    #   @author.books                              # selects all books by using the Authorship join model 
    356356    #  
    357     # You can also go through a has_many association on the join model: 
     357    # You can also go through a +has_many+ association on the join model: 
    358358    #  
    359359    #   class Firm < ActiveRecord::Base 
    360360    #     has_many   :clients 
    …… 
    377377    # === Polymorphic Associations 
    378378    #  
    379379    # Polymorphic associations on models are not restricted on what types of models they can be associated with.  Rather, they  
    380     # specify an interface that a has_many association must adhere to. 
     380    # specify an interface that a +has_many+ association must adhere to. 
    381381    #  
    382382    #   class Asset < ActiveRecord::Base 
    383383    #     belongs_to :attachable, :polymorphic => true 
    384384    #   end 
    385385    #  
    386386    #   class Post < ActiveRecord::Base 
    387     #     has_many :assets, :as => :attachable         # The <tt>:as</tt> option specifies the polymorphic interface to use. 
     387    #     has_many :assets, :as => :attachable         # The :as option specifies the polymorphic interface to use. 
    388388    #   end 
    389389    # 
    390390    #   @asset.attachable = @post 
    391391    #  
    392392    # This works by using a type column in addition to a foreign key to specify the associated record.  In the Asset example, you'd need 
    393     # an attachable_id integer column and an attachable_type string column. 
     393    # an +attachable_id+ integer column and an +attachable_type+ string column. 
    394394    # 
    395395    # Using polymorphic associations in combination with single table inheritance (STI) is a little tricky. In order 
    396396    # for the associations to work as expected, ensure that you store the base model for the STI models in the  
    397397    # type column of the polymorphic association. To continue with the asset example above, suppose there are guest posts 
    398     # and member posts that use the posts table for STI. So there will be an additional 'type' column in the posts table. 
     398    # and member posts that use the posts table for STI. In this case, there must be a +type+ column in the posts table. 
    399399    # 
    400400    #   class Asset < ActiveRecord::Base 
    401401    #     belongs_to :attachable, :polymorphic => true 
    …… 
    431431    # == Eager loading of associations 
    432432    # 
    433433    # Eager loading is a way to find objects of a certain class and a number of named associations along with it in a single SQL call. This is 
    434     # one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100 posts that each needs to display their author 
     434    # one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100 posts that each need to display their author 
    435435    # triggers 101 database queries. Through the use of eager loading, the 101 queries can be reduced to 1. Example: 
    436436    # 
    437437    #   class Post < ActiveRecord::Base 
    …… 
    451451    # 
    452452    #   for post in Post.find(:all, :include => :author) 
    453453    # 
    454     # This references the name of the belongs_to association that also used the :author symbol, so the find will now weave in a join something 
    455     # like this: LEFT OUTER JOIN authors ON authors.id = posts.author_id. Doing so will cut down the number of queries from 201 to 101. 
     454    # This references the name of the +belongs_to+ association that also used the <tt>:author</tt> symbol, so the find will now weave in a join something 
     455    # like this: <tt>LEFT OUTER JOIN authors ON authors.id = posts.author_id</tt>. Doing so will cut down the number of queries from 201 to 101. 
    456456    # 
    457457    # We can improve upon the situation further by referencing both associations in the finder with: 
    458458    # 
    459459    #   for post in Post.find(:all, :include => [ :author, :comments ]) 
    460460    # 
    461     # That'll add another join along the lines of: LEFT OUTER JOIN comments ON comments.post_id = posts.id. And we'll be down to 1 query. 
     461    # That'll add another join along the lines of: <tt>LEFT OUTER JOIN comments ON comments.post_id = posts.id</tt>. And we'll be down to 1 query. 
    462462    # 
    463     # To include a deep hierarchy of associations, using a hash: 
     463    # To include a deep hierarchy of associations, use a hash: 
    464464    # 
    465465    #   for post in Post.find(:all, :include => [ :author, { :comments => { :author => :gravatar } } ]) 
    466466    # 
    …… 
    472472    # catch-all for performance problems, but it's a great way to cut down on the number of queries in a situation as the one described above. 
    473473    #  
    474474    # Since the eager loading pulls from multiple tables, you'll have to disambiguate any column references in both conditions and orders. So 
    475     # :order => "posts.id DESC" will work while :order => "id DESC" will not. Because eager loading generates the SELECT statement too, the 
    476     # :select option is ignored. 
     475    # <tt>:order => "posts.id DESC"</tt> will work while <tt>:order => "id DESC"</tt> will not. Because eager loading generates the +SELECT+ statement too, the 
     476    # <tt>:select</tt> option is ignored. 
    477477    # 
    478478    # You can use eager loading on multiple associations from the same table, but you cannot use those associations in orders and conditions 
    479479    # as there is currently not any way to disambiguate them. Eager loading will not pull additional attributes on join tables, so "rich 
    480     # associations" with has_and_belongs_to_many are not a good fit for eager loading. 
     480    # associations" with +has_and_belongs_to_many+ are not a good fit for eager loading. 
    481481    #  
    482482    # When eager loaded, conditions are interpolated in the context of the model class, not the model instance.  Conditions are lazily interpolated 
    483483    # before the actual model exists. 
    …… 
    485485    # == Table Aliasing 
    486486    # 
    487487    # ActiveRecord uses table aliasing in the case that a table is referenced multiple times in a join.  If a table is referenced only once, 
    488     # the standard table name is used.  The second time, the table is aliased as #{reflection_name}_#{parent_table_name}.  Indexes are appended 
     488    # the standard table name is used.  The second time, the table is aliased as <tt>#{reflection_name}_#{parent_table_name}</tt>.  Indexes are appended 
    489489    # for any more successive uses of the table name. 
    490490    #  
    491491    #   Post.find :all, :include => :comments 
    …… 
    505505    #   TreeMixin.find :all, :include => {:children => {:parent => :children}}  
    506506    #   # => SELECT ... FROM mixins LEFT OUTER JOIN mixins childrens_mixins ...  
    507507    #                               LEFT OUTER JOIN parents_mixins ...  
    508     # LEFT OUTER JOIN mixins childrens_mixins_2 
     508    #                               LEFT OUTER JOIN mixins childrens_mixins_2 
    509509    #  
    510     # Has and Belongs to Many join tables use the same idea, but add a _join suffix: 
     510    # Has and Belongs to Many join tables use the same idea, but add a <tt>_join</tt> suffix: 
    511511    #  
    512512    #   Post.find :all, :include => :categories 
    513513    #   # => SELECT ... FROM posts LEFT OUTER JOIN categories_posts ... LEFT OUTER JOIN categories ... 
    …… 
    519519    #                              LEFT OUTER JOIN categories_posts posts_categories_join LEFT OUTER JOIN posts posts_categories 
    520520    #                              LEFT OUTER JOIN categories_posts categories_posts_join LEFT OUTER JOIN categories categories_posts 
    521521    #  
    522     # If you wish to specify your own custom joins using a :joins option, those table names will take precedence over the eager associations.. 
     522    # If you wish to specify your own custom joins using a <tt>:joins</tt> option, those table names will take precedence over the eager associations: 
    523523    #  
    524524    #   Post.find :all, :include => :comments, :joins => "inner join comments ..." 
    525525    #   # => SELECT ... FROM posts LEFT OUTER JOIN comments_posts ON ... INNER JOIN comments ... 
    …… 
    544544    #     end 
    545545    #   end 
    546546    # 
    547     # When Firm#clients is called, it'll in turn call <tt>MyApplication::Business::Company.find(firm.id)</tt>. If you want to associate 
    548     # with a class in another module scope this can be done by specifying the complete class name, such as: 
     547    # When <tt>Firm#clients</tt> is called, it will in turn call <tt>MyApplication::Business::Company.find(firm.id)</tt>. If you want to associate 
     548    # with a class in another module scope, this can be done by specifying the complete class name.  Example: 
    549549    # 
    550550    #   module MyApplication 
    551551    #     module Business 
    …… 
    559559    #     end 
    560560    #   end 
    561561    # 
    562     # == Type safety with ActiveRecord::AssociationTypeMismatch 
     562    # == Type safety with <tt>ActiveRecord::AssociationTypeMismatch</tt> 
    563563    # 
    564564    # If you attempt to assign an object to an association that doesn't match the inferred or specified <tt>:class_name</tt>, you'll 
    565     # get a ActiveRecord::AssociationTypeMismatch. 
     565    # get an <tt>ActiveRecord::AssociationTypeMismatch</tt>. 
    566566    # 
    567567    # == Options 
    568568    # 
    569     # All of the association macros can be specialized through options which makes more complex cases than the simple and guessable ones 
     569    # All of the association macros can be specialized through options. This makes cases more complex than the simple and guessable ones 
    570570    # possible. 
    571571    module ClassMethods 
    572       # Adds the following methods for retrieval and query of collections of associated objects. 
     572      # Adds the following methods for retrieval and query of collections of associated objects: 
    573573      # +collection+ is replaced with the symbol passed as the first argument, so  
    574574      # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>. 
    575575      # * <tt>collection(force_reload = false)</tt> - returns an array of all the associated objects. 
    576576      #   An empty array is returned if none are found. 
    577577      # * <tt>collection<<(object, ...)</tt> - adds one or more objects to the collection by setting their foreign keys to the collection's primary key. 
    578578      # * <tt>collection.delete(object, ...)</tt> - removes one or more objects from the collection by setting their foreign keys to NULL.   
    579       #   This will also destroy the objects if they're declared as belongs_to and dependent on this model. 
     579      #   This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model. 
    580580      # * <tt>collection=objects</tt> - replaces the collections content by deleting and adding objects as appropriate. 
    581       # * <tt>collection_singular_ids</tt> - returns an array of the associated objects ids 
     581      # * <tt>collection_singular_ids</tt> - returns an array of the associated objects' ids 
    582582      # * <tt>collection_singular_ids=ids</tt> - replace the collection by the objects identified by the primary keys in +ids+ 
    583583      # * <tt>collection.clear</tt> - removes every object from the collection. This destroys the associated objects if they 
    584584      #   are associated with <tt>:dependent => :destroy</tt>, deletes them directly from the database if <tt>:dependent => :delete_all</tt>, 
    585       #   and sets their foreign keys to NULL otherwise. 
    586       # * <tt>collection.empty?</tt> - returns true if there are no associated objects. 
     585      #   or otherwise sets their foreign keys to NULL. 
     586      # * <tt>collection.empty?</tt> - returns +true+ if there are no associated objects. 
    587587      # * <tt>collection.size</tt> - returns the number of associated objects. 
    588588      # * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find. 
    589589      # * <tt>collection.build(attributes = {}, ...)</tt> - returns one or more new objects of the collection type that have been instantiated 
    590       #   with +attributes+ and linked to this object through a foreign key but have not yet been saved. *Note:* This only works if an  
    591       #   associated object already exists, not if it's nil! 
     590      #   with +attributes+ and linked to this object through a foreign key, but have not yet been saved. *Note:* This only works if an  
     591      #   associated object already exists, not if it's +nil+! 
    592592      # * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated 
    593       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation). 
    594       #   *Note:* This only works if an associated object already exists, not if it's nil! 
     593      #   with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). 
     594      #   *Note:* This only works if an associated object already exists, not if it's +nil+! 
    595595      # 
    596       # Example: A Firm class declares <tt>has_many :clients</tt>, which will add: 
     596      # Example: A +Firm+ class declares <tt>has_many :clients</tt>, which will add: 
    597597      # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>) 
    598598      # * <tt>Firm#clients<<</tt> 
    599599      # * <tt>Firm#clients.delete</tt> 
    …… 
    612612      # * <tt>:class_name</tt>  - specify the class name of the association. Use it only if that name can't be inferred 
    613613      #   from the association name. So <tt>has_many :products</tt> will by default be linked to the +Product+ class, but 
    614614      #   if the real class name is +SpecialProduct+, you'll have to specify it with this option. 
    615       # * <tt>:conditions</tt>  - specify the conditions that the associated objects must meet in order to be included as a "WHERE" 
    616       #   sql fragment, such as "price > 5 AND name LIKE 'B%'". 
    617       # * <tt>:order</tt>       - specify the order in which the associated objects are returned as a "ORDER BY" sql fragment, 
    618       #   such as "last_name, first_name DESC" 
    619       # * <tt>:group</tt>       - specify the attribute by which the associated objects are returned as a "GROUP BY" sql fragment, 
    620       #   such as "category"       
     615      # * <tt>:conditions</tt>  - specify the conditions that the associated objects must meet in order to be included as a +WHERE+ 
     616      #   SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>. 
     617      # * <tt>:order</tt>       - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment, 
     618      #   such as <tt>last_name, first_name DESC</tt> 
     619      # * <tt>:group</tt>       - specify the attribute by which the associated objects are returned as a <tt>GROUP BY</tt> SQL fragment, 
     620      #   such as +category+ 
    621621      # * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name 
    622       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_many association will use "person_id" 
    623       #   as the default foreign_key. 
    624       # * <tt>:dependent</tt>   - if set to :destroy all the associated objects are destroyed 
    625       #   alongside this object by calling their destroy method.  If set to :delete_all all associated 
    626       #   objects are deleted *without* calling their destroy method.  If set to :nullify all associated 
    627       #   objects' foreign keys are set to NULL *without* calling their save callbacks. 
    628       #   NOTE: :dependent => true is deprecated and has been replaced with :dependent => :destroy.  
    629       #   May not be set if :exclusively_dependent is also set. 
    630       # * <tt>:exclusively_dependent</tt>   - Deprecated; equivalent to :dependent => :delete_all. If set to true all 
    631       #   the associated object are deleted in one SQL statement without having their 
    632       #   before_destroy callback run. This should only be used on associations that depend solely on this class and don't need to do any 
    633       #   clean-up in before_destroy. The upside is that it's much faster, especially if there's a counter_cache involved. 
    634       #   May not be set if :dependent is also set. 
     622      #   of this class in lower-case and +_id+ suffixed. So a +Person+ class that makes a +has_many+ association will use +person_id+ 
     623      #   as the default +foreign_key+. 
     624      # * <tt>:dependent</tt>   - if set to <tt>:destroy</tt> all the associated objects are destroyed 
     625      #   alongside this object by calling their destroy method.  If set to <tt>:delete_all</tt> all associated 
     626      #   objects are deleted *without* calling their destroy method.  If set to <tt>:nullify</tt> all associated 
     627      #   objects' foreign keys are set to +NULL+ *without* calling their save callbacks. 
     628      #   NOTE: <tt>:dependent => true</tt> is deprecated and has been replaced with <tt>:dependent => :destroy</tt>.  
     629      #   May not be set if <tt>:exclusively_dependent</tt> is also set. 
     630      # * <tt>:exclusively_dependent</tt>   - Deprecated; equivalent to <tt>:dependent => :delete_all</tt>. If set to +true+ all 
     631      #   the associated objects are deleted in one SQL statement without having their 
     632      #   +before_destroy+ callback run. This should only be used on associations that depend solely on this class and don't need to do any 
     633      #   clean-up in +before_destroy+. The upside is that it's much faster, especially if there's a +counter_cache+ involved. 
     634      #   May not be set if <tt>:dependent</tt> is also set. 
    635635      # * <tt>:finder_sql</tt>  - specify a complete SQL statement to fetch the association. This is a good way to go for complex 
    636636      #   associations that depend on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added. 
    637       # * <tt>:counter_sql</tt>  - specify a complete SQL statement to fetch the size of the association. If +:finder_sql+ is 
    638       #   specified but +:counter_sql+, +:counter_sql+ will be generated by replacing SELECT ... FROM with SELECT COUNT(*) FROM. 
    639       # * <tt>:extend</tt>  - specify a named module for extending the proxy, see "Association extensions". 
     637      # * <tt>:counter_sql</tt>  - specify a complete SQL statement to fetch the size of the association. If <tt>:finder_sql</tt> is 
     638      #   specified but <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>. 
     639      # * <tt>:extend</tt>  - specify a named module for extending the proxy. See "Association extensions". 
    640640      # * <tt>:include</tt>  - specify second-order associations that should be eager loaded when the collection is loaded. 
    641       # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. 
     641      # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause. 
    642642      # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned. 
    643643      # * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows. 
    644       # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not 
    645       #   include the joined columns. 
    646       # * <tt>:as</tt>: Specifies a polymorphic interface (See #belongs_to). 
    647       # * <tt>:through</tt>: Specifies a Join Model to perform the query through.  Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>  
     644      # * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you for example want to do a join,  
     645      #   but not include the joined columns. 
     646      # * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>). 
     647      # * <tt>:through</tt>: Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>  
    648648      #   are ignored, as the association uses the source reflection. You can only use a <tt>:through</tt> query through a <tt>belongs_to</tt> 
    649649      #   or <tt>has_many</tt> association on the join model. 
    650650      # * <tt>:source</tt>: Specifies the source association name used by <tt>has_many :through</tt> queries.  Only use it if the name cannot be  
    651       #   inferred from the association.  <tt>has_many :subscribers, :through => :subscriptions</tt> will look for either +:subscribers+ or 
    652       #   +:subscriber+ on +Subscription+, unless a +:source+ is given. 
    653       # * <tt>:source_type</tt>: Specifies type of the source association used by <tt>has_many :through</tt> queries where the source association 
    654       #   is a polymorphic belongs_to. 
    655       # * <tt>:uniq</tt> - if set to true, duplicates will be omitted from the collection. Useful in conjunction with :through. 
     651      #   inferred from the association.  <tt>has_many :subscribers, :through => :subscriptions</tt> will look for either <tt>:subscribers</tt> or 
     652      #   <tt>:subscriber</tt> on +Subscription+, unless a <tt>:source</tt> is given. 
     653      # * <tt>:source_type</tt>: Specifies type of the source association used by <tt>has_many :through</tt> queries where the source 
     654      #   association is a polymorphic +belongs_to+. 
     655      # * <tt>:uniq</tt> - if set to +true+, duplicates will be omitted from the collection. Useful in conjunction with <tt>:through</tt>. 
    656656      # 
    657657      # Option examples: 
    658658      #   has_many :comments, :order => "posted_on" 
    …… 
    684684        add_deprecated_api_for_has_many(reflection.name) 
    685685      end 
    686686 
    687       # Adds the following methods for retrieval and query of a single associated object. 
     687      # Adds the following methods for retrieval and query of a single associated object: 
    688688      # +association+ is replaced with the symbol passed as the first argument, so  
    689689      # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>. 
    690       # * <tt>association(force_reload = false)</tt> - returns the associated object. Nil is returned if none is found. 
     690      # * <tt>association(force_reload = false)</tt> - returns the associated object. +nil+ is returned if none is found. 
    691691      # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, sets it as the foreign key,  
    692692      #   and saves the associate object. 
    693       # * <tt>association.nil?</tt> - returns true if there is no associated object. 
     693      # * <tt>association.nil?</tt> - returns +true+ if there is no associated object. 
    694694      # * <tt>build_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated 
    695       #   with +attributes+ and linked to this object through a foreign key but has not yet been saved. Note: This ONLY works if 
    696       #   an association already exists. It will NOT work if the association is nil. 
     695      #   with +attributes+ and linked to this object through a foreign key, but has not yet been saved. Note: This ONLY works if 
     696      #   an association already exists. It will NOT work if the association is +nil+. 
    697697      # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated 
    698       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation). 
     698      #   with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). 
    699699      # 
    700700      # Example: An Account class declares <tt>has_one :beneficiary</tt>, which will add: 
    701701      # * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.find(:first, :conditions => "account_id = #{id}")</tt>) 
    …… 
    710710      # * <tt>:class_name</tt>  - specify the class name of the association. Use it only if that name can't be inferred 
    711711      #   from the association name. So <tt>has_one :manager</tt> will by default be linked to the +Manager+ class, but 
    712712      #   if the real class name is +Person+, you'll have to specify it with this option. 
    713       # * <tt>:conditions</tt>  - specify the conditions that the associated object must meet in order to be included as a "WHERE" 
    714       #   sql fragment, such as "rank = 5". 
     713      # * <tt>:conditions</tt>  - specify the conditions that the associated object must meet in order to be included as a +WHERE+ 
     714      #   SQL fragment, such as <tt>rank = 5</tt>. 
    715715      # * <tt>:order</tt>       - specify the order from which the associated object will be picked at the top. Specified as 
    716       #    an "ORDER BY" sql fragment, such as "last_name, first_name DESC" 
    717       # * <tt>:dependent</tt>   - if set to :destroy (or true) the associated object is destroyed when this object is. If set to 
    718       #   :delete the associated object is deleted *without* calling its destroy method. If set to :nullify the associated 
    719       #   object's foreign key is set to NULL. Also, association is assigned. 
     716      #   an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt> 
     717      # * <tt>:dependent</tt>   - if set to <tt>:destroy</tt> (or +true+), the associated object is destroyed when this object is. If set to 
     718      #   <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method. If set to <tt>:nullify</tt>, the associated 
     719      #   object's foreign key is set to +NULL+. Also, association is assigned. 
    720720      # * <tt>:foreign_key</tt> - specify the foreign key used for the association. By default this is guessed to be the name 
    721       #   of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_one association will use "person_id" 
    722       #   as the default foreign_key. 
     721      #   of this class in lower-case and +_id+ suffixed. So a +Person+ class that makes a +has_one+ association will use +person_id+ 
     722      #   as the default +foreign_key+. 
    723723      # * <tt>:include</tt>  - specify second-order associations that should be eager loaded when this object is loaded. 
    724       # * <tt>:as</tt>: Specifies a polymorphic interface (See #belongs_to). 
     724      # * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>). 
    725725            # 
    726726      # Option examples: 
    727727      #   has_one :credit_card, :dependent => :destroy  # destroys the associated credit card 
    …… 
    753753        deprecated_association_comparison_method(reflection.name, reflection.class_name) 
    754754      end 
    755755 
    756       # Adds the following methods for retrieval and query for a single associated object that this object holds an id to. 
     756      # Adds the following methods for retrieval and query for a single associated object for which this object holds an id: 
    757757      # +association+ is replaced with the symbol passed as the first argument, so  
    758758      # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>. 
    759       # * <tt>association(force_reload = false)</tt> - returns the associated object. Nil is returned if none is found. 
     759      # * <tt>association(force_reload = false)</tt> - returns the associated object. +nil+ is returned if none is found. 
    760760      # * <tt>association=(associate)</tt> - assigns the associate object, extracts the primary key, and sets it as the foreign key. 
    761       # * <tt>association.nil?</tt> - returns true if there is no associated object. 
     761      # * <tt>association.nil?</tt> - returns +true+ if there is no associated object. 
    762762      # * <tt>build_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated 
    763       #   with +attributes+ and linked to this object through a foreign key but has not yet been saved. 
     763      #   with +attributes+ and linked to this object through a foreign key, but has not yet been saved. 
    764764      # * <tt>create_association(attributes = {})</tt> - returns a new object of the associated type that has been instantiated 
    765       #   with +attributes+ and linked to this object through a foreign key and that has already been saved (if it passed the validation). 
     765      #   with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). 
    766766