README.md in acts_as-0.0.2 vs README.md in acts_as-0.0.3

@@ -1,8 +1,8 @@
 # ActsAs
 
-ActiveRecord extension for easy 1:1 composition delegation
+ActiveRecord extension for easy belongs_to composition delegation
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
@@ -18,22 +18,24 @@
 
 ## Usage
 
 ```ruby
 
+# This pattern encourages foreign keys to be stored on the STI's root table for easy reads.
+#
 # table :users
 #   name :string
+#   clan_id :integer
+#   profile_id :integer
 #
 class User
   include ActsAs
 end
 
 class Rebel < User
-  has_one :profile, class_name: 'RebelProfile', autosave: true
-  belongs_to :clan, autosave: true
-  acts_as :profile
-  acts_as :clan, prefix: %w( name ), whitelist: %w( delegate_at_will )
+  acts_as :profile, class_name: 'RebelProfile', autosave: true
+  acts_as :clan, prefix: %w( name ), with: %w( delegate_at_will ), autosave: true
 end
 
 # table :clans
 #   name :string
 #   strength :integer
@@ -46,15 +48,14 @@
     '10'
   end
 end
 
 # table :rebel_profiles
-#   rebel_id :integer
 #   serial_data :string
 #
 class RebelProfile < ActiveRecord::Base
-  belongs_to :rebel
+  has_one :rebel
 end
 
 ```
 
 Now a whole slew of methods related to ActiveRecord attributes are available for the fields being delegated to another table
@@ -82,10 +83,10 @@
 How does the active record join hash-parsing stuff work? EX-
 
     Rebel.joins(:clan).where(clan: {cool: true)
 
 Can we make this work for ruby-sql autojoins? Is that even a good idea?
-    Rebel.where(cool: true)
+    Rebel.where(cool: true) #auto-joins :clan
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)