Structure change to AR Associations Guide

2 files changed, 13 insertions, 4 deletions

diff --git a/railties/doc/guides/html/association_basics.html b/railties/doc/guides/html/association_basics.html
index 9159eaab2a..e8cad6c220 100644
--- a/railties/doc/guides/html/association_basics.html
+++ b/railties/doc/guides/html/association_basics.html
@@ -742,7 +742,9 @@ customer<span style="color: #990000">.</span>orders<span style="color: #990000">
 <h3 id="_avoiding_name_collisions">3.2. Avoiding Name Collisions</h3>

 <div class="para"><p>You are not free to use just any name for your associations. Because creating an association adds a method with that name to the model, it is a bad idea to give an association a name that is already used for an instance method of <tt>ActiveRecord::Base</tt>. The association method would override the base method and break things. For instance, <tt>attributes</tt> or <tt>connection</tt> are bad names for associations.</p></div>

 <h3 id="_updating_the_schema">3.3. Updating the Schema</h3>

-<div class="para"><p>Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things. First, you need to create foreign keys as appropriate:</p></div>

+<div class="para"><p>Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things, depending on what sort of associations you are creating. For <tt>belongs_to</tt> associations you need to create foreign keys, and for <tt>has_and_belongs_to_many</tt> associations you need to create the appropriate join table.</p></div>

+<h4 id="_creating_foreign_keys_for_tt_belongs_to_tt_associations">3.3.1. Creating Foreign Keys for <tt>belongs_to</tt> Associations</h4>

+<div class="para"><p>When you declare a <tt>belongs_to</tt> association, you need to create foreign keys as appropriate. For example, consider this model:</p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

@@ -773,7 +775,8 @@ http://www.gnu.org/software/src-highlite -->
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 </tt></pre></div></div>

 <div class="para"><p>If you create an association some time after you build the underlying model, you need to remember to create an <tt>add_column</tt> migration to provide the necessary foreign key.</p></div>

-<div class="para"><p>Second, if you create a <tt>has_and_belongs_to_many</tt> association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the <tt>:join_table</tt> option, Active Record create the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering.</p></div>

+<h4 id="_creating_join_tables_for_tt_has_and_belongs_to_many_tt_associations">3.3.2. Creating Join Tables for <tt>has_and_belongs_to_many</tt> Associations</h4>

+<div class="para"><p>If you create a <tt>has_and_belongs_to_many</tt> association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the <tt>:join_table</tt> option, Active Record create the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering.</p></div>

 <div class="admonitionblock">

 <table><tr>

 <td class="icon">

diff --git a/railties/doc/guides/source/association_basics.txt b/railties/doc/guides/source/association_basics.txt
index 5ba616642b..e0c9ee35d3 100644
--- a/railties/doc/guides/source/association_basics.txt
+++ b/railties/doc/guides/source/association_basics.txt
@@ -396,7 +396,11 @@ You are not free to use just any name for your associations. Because creating an
 
 === Updating the Schema
 
-Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things. First, you need to create foreign keys as appropriate:
+Associations are extremely useful, but they are not magic. You are responsible for maintaining your database schema to match your associations. In practice, this means two things, depending on what sort of associations you are creating. For +belongs_to+ associations you need to create foreign keys, and for +has_and_belongs_to_many+ associations you need to create the appropriate join table.
+
+==== Creating Foreign Keys for +belongs_to+ Associations
+
+When you declare a +belongs_to+ association, you need to create foreign keys as appropriate. For example, consider this model:
 
 [source, ruby]
 -------------------------------------------------------
@@ -426,7 +430,9 @@ end
 
 If you create an association some time after you build the underlying model, you need to remember to create an +add_column+ migration to provide the necessary foreign key.
 
-Second, if you create a +has_and_belongs_to_many+ association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the +:join_table+ option, Active Record create the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering. 
+==== Creating Join Tables for +has_and_belongs_to_many+ Associations
+
+If you create a +has_and_belongs_to_many+ association, you need to explicitly create the joining table. Unless the name of the join table is explicitly specified by using the +:join_table+ option, Active Record create the name by using the lexical order of the class names. So a join between customer and order models will give the default join table name of "customers_orders" because "c" outranks "o" in lexical ordering. 
 
 WARNING: The precedence between model names is calculated using the +<+ operator for +String+. This means that if the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered of higher lexical precedence than the shorter one. For example, one would expect the tables "paper_boxes" and "papers" to generate a join table name of "papers_paper_boxes" because of the length of the name "paper_boxes", but it in fact generates a join table name of "paper_boxes_papers".