Merge remote branch 'docrails/master'

actionmailer/lib/action_mailer/base.rb

@@ -129,7 +129,7 @@ module ActionMailer #:nodoc:
   #
   #   ActionMailer::Base.default_url_options[:host] = "example.com"
   #
-  # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
+  # This can also be set as a configuration option in <tt>config/application.rb</tt>:
   #
   #   config.action_mailer.default_url_options = { :host => "example.com" }
   #

actionpack/lib/action_controller/metal/mime_responds.rb

@@ -145,7 +145,7 @@ def clear_respond_to
     # and accept Rails' defaults, life will be much easier.
     #
     # If you need to use a MIME type which isn't supported by default, you can register your own handlers in
-    # environment.rb as follows.
+    # config/initializers/mime_types.rb as follows.
     #
     #   Mime::Type.register "image/jpg", :jpg
     #

actionpack/lib/action_dispatch/middleware/session/cookie_store.rb

@@ -35,7 +35,7 @@ module Session
     #   such as 'MD5', 'RIPEMD160', 'SHA256', etc.
     #
     # To generate a secret key for an existing application, run
-    # "rake secret" and set the key in config/environment.rb.
+    # "rake secret" and set the key in config/initializers/secret_token.rb.
     #
     # Note that changing digest or secret invalidates all existing sessions!
     class CookieStore < AbstractStore

actionpack/lib/action_dispatch/routing.rb

@@ -31,7 +31,7 @@ module ActionDispatch
   # Think of creating routes as drawing a map for your requests. The map tells
   # them where to go based on some predefined pattern:
   #
-  #   AppName::Application.routes.draw do |map|
+  #   AppName::Application.routes.draw do
   #     Pattern 1 tells some request to go to one place
   #     Pattern 2 tell them to go to another
   #     ...

actionpack/lib/action_view/helpers/atom_feed_helper.rb

@@ -10,7 +10,7 @@ module AtomFeedHelper
       # Full usage example:
       #
       #   config/routes.rb:
-      #     Basecamp::Application.routes.draw do |map|
+      #     Basecamp::Application.routes.draw do
       #       resources :posts
       #       root :to => "posts#index"
       #     end

actionpack/lib/action_view/helpers/sanitize_helper.rb

@@ -32,21 +32,21 @@ module SanitizeHelper
       #
       # Add table tags to the default allowed tags
       #
-      #   Rails::Initializer.run do |config|
+      #   class Application < Rails::Application
       #     config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
       #   end
       #
       # Remove tags to the default allowed tags
       #
-      #   Rails::Initializer.run do |config|
+      #   class Application < Rails::Application
       #     config.after_initialize do
       #       ActionView::Base.sanitized_allowed_tags.delete 'div'
       #     end
       #   end
       #
       # Change allowed default attributes
       #
-      #   Rails::Initializer.run do |config|
+      #   class Application < Rails::Application
       #     config.action_view.sanitized_allowed_attributes = 'id', 'class', 'style'
       #   end
       #
@@ -143,7 +143,7 @@ def sanitized_protocol_separator=(value)
         # Gets the HTML::FullSanitizer instance used by +strip_tags+.  Replace with
         # any object that responds to +sanitize+.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.full_sanitizer = MySpecialSanitizer.new
         #   end
         #
@@ -154,7 +154,7 @@ def full_sanitizer
         # Gets the HTML::LinkSanitizer instance used by +strip_links+.  Replace with
         # any object that responds to +sanitize+.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.link_sanitizer = MySpecialSanitizer.new
         #   end
         #
@@ -165,7 +165,7 @@ def link_sanitizer
         # Gets the HTML::WhiteListSanitizer instance used by sanitize and +sanitize_css+.
         # Replace with any object that responds to +sanitize+.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.white_list_sanitizer = MySpecialSanitizer.new
         #   end
         #
@@ -175,7 +175,7 @@ def white_list_sanitizer
 
         # Adds valid HTML attributes that the +sanitize+ helper checks for URIs.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_uri_attributes = 'lowsrc', 'target'
         #   end
         #
@@ -185,7 +185,7 @@ def sanitized_uri_attributes=(attributes)
 
         # Adds to the Set of 'bad' tags for the +sanitize+ helper.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_bad_tags = 'embed', 'object'
         #   end
         #
@@ -195,7 +195,7 @@ def sanitized_bad_tags=(attributes)
 
         # Adds to the Set of allowed tags for the +sanitize+ helper.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
         #   end
         #
@@ -205,7 +205,7 @@ def sanitized_allowed_tags=(attributes)
 
         # Adds to the Set of allowed HTML attributes for the +sanitize+ helper.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_allowed_attributes = 'onclick', 'longdesc'
         #   end
         #
@@ -215,7 +215,7 @@ def sanitized_allowed_attributes=(attributes)
 
         # Adds to the Set of allowed CSS properties for the #sanitize and +sanitize_css+ helpers.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_allowed_css_properties = 'expression'
         #   end
         #
@@ -225,7 +225,7 @@ def sanitized_allowed_css_properties=(attributes)
 
         # Adds to the Set of allowed CSS keywords for the +sanitize+ and +sanitize_css+ helpers.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_allowed_css_keywords = 'expression'
         #   end
         #
@@ -235,7 +235,7 @@ def sanitized_allowed_css_keywords=(attributes)
 
         # Adds to the Set of allowed shorthand CSS properties for the +sanitize+ and +sanitize_css+ helpers.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_shorthand_css_properties = 'expression'
         #   end
         #
@@ -245,7 +245,7 @@ def sanitized_shorthand_css_properties=(attributes)
 
         # Adds to the Set of allowed protocols for the +sanitize+ helper.
         #
-        #   Rails::Initializer.run do |config|
+        #   class Application < Rails::Application
         #     config.action_view.sanitized_allowed_protocols = 'ssh', 'feed'
         #   end
         #

activerecord/lib/active_record/connection_adapters/mysql_adapter.rb

@@ -125,7 +125,7 @@ class MysqlAdapter < AbstractAdapter
       # By default, the MysqlAdapter will consider all columns of type <tt>tinyint(1)</tt>
       # as boolean. If you wish to disable this emulation (which was the default
       # behavior in versions 0.13.1 and earlier) you can add the following line
-      # to your environment.rb file:
+      # to your application.rb file:
       #
       #   ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans = false
       cattr_accessor :emulate_booleans

activerecord/lib/active_record/migration.rb

@@ -284,7 +284,7 @@ def initialize(name)
   #
   #    config.active_record.timestamped_migrations = false
   #
-  # In environment.rb.
+  # In application.rb.
   #
   class Migration
     @@verbose = true

activerecord/lib/active_record/observer.rb

@@ -68,7 +68,7 @@ module ActiveRecord
   # == Configuration
   #
   # In order to activate an observer, list it in the <tt>config.active_record.observers</tt> configuration setting in your
-  # <tt>config/environment.rb</tt> file.
+  # <tt>config/application.rb</tt> file.
   #
   #   config.active_record.observers = :comment_observer, :signup_observer
   #

activerecord/lib/active_record/session_store.rb

@@ -16,7 +16,7 @@ module ActiveRecord
   # ActionController::SessionOverflowError will be raised.
   #
   # You may configure the table name, primary key, and data column.
-  # For example, at the end of <tt>config/environment.rb</tt>:
+  # For example, at the end of <tt>config/application.rb</tt>:
   #
   #   ActiveRecord::SessionStore::Session.table_name = 'legacy_session_table'
   #   ActiveRecord::SessionStore::Session.primary_key = 'session_id'

activesupport/lib/active_support/values/time_zone.rb

@@ -8,10 +8,10 @@
 # * Lazily load TZInfo::Timezone instances only when they're needed.
 # * Create ActiveSupport::TimeWithZone instances via TimeZone's +local+, +parse+, +at+ and +now+ methods.
 #
-# If you set <tt>config.time_zone</tt> in the Rails Initializer, you can access this TimeZone object via <tt>Time.zone</tt>:
+# If you set <tt>config.time_zone</tt> in the Rails Application, you can access this TimeZone object via <tt>Time.zone</tt>:
 #
-#   # environment.rb:
-#   Rails::Initializer.run do |config|
+#   # application.rb:
+#   class Application < Rails::Application
 #     config.time_zone = "Eastern Time (US & Canada)"
 #   end
 #

railties/guides/source/association_basics.textile

@@ -1371,7 +1371,41 @@ The +:through+ option specifies a join model through which to perform the query.
 
 h6(#has_many-uniq). +:uniq+
 
-Specify the +:uniq => true+ option to remove duplicates from the collection. This is most useful in conjunction with the +:through+ option.
+Set the +:uniq+ option to true to keep the collection free of duplicates. This is mostly useful together with the +:through+ option.
+
+<ruby>
+class Person < ActiveRecord::Base
+  has_many :readings
+  has_many :posts, :through => :readings
+end
+
+person = Person.create(:name => 'john')
+post   = Post.create(:name => 'a1')
+person.posts << post
+person.posts << post
+person.posts.inspect # => [#<Post id: 5, name: "a1">, #<Post id: 5, name: "a1">]
+Reading.all.inspect  # => [#<Reading id: 12, person_id: 5, post_id: 5>, #<Reading id: 13, person_id: 5, post_id: 5>]
+</ruby>
+
+In the above case there are two readings and +person.posts+ brings out both of them even though these records are pointing to the same post.
+
+Now let's set +:uniq+ to true:
+
+<ruby>
+class Person
+  has_many :readings
+  has_many :posts, :through => :readings, :uniq => true
+end
+
+person = Person.create(:name => 'honda')
+post   = Post.create(:name => 'a1')
+person.posts << post
+person.posts << post
+person.posts.inspect # => [#<Post id: 7, name: "a1">] 
+Reading.all.inspect  # => [#<Reading id: 16, person_id: 7, post_id: 7>, #<Reading id: 17, person_id: 7, post_id: 7>] 
+</ruby>
+
+In the above case there are still two readings. However +person.posts+ shows only one post because the collection loads only unique records.
 
 h6(#has_many-validate). +:validate+
 

railties/guides/source/getting_started.textile

@@ -322,16 +322,15 @@ $ rm public/index.html
 
 We need to do this as Rails will deliver any static file in the +public+ directory in preference to any dynamic contact we generate from the controllers.
 
-Now, you have to tell Rails where your actual home page is located. Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. There are only comments in this file, so we need to add at the top the following:
+Now, you have to tell Rails where your actual home page is located. Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +:root to+, uncomment it and change it like the following:
 
 <ruby>
-Blog::Application.routes.draw do |map|
+Blog::Application.routes.draw do
 
-  root :to => "home#index"
-
-  # The priority is based upon order of creation:
-  # first created -> highest priority.
   #...
+  # You can have the root of your site routed with "root"
+  # just remember to delete public/index.html.
+  root :to => "home#index"
 </ruby>
 
 The +root :to => "home#index"+ tells Rails to map the root action to the home controller's index action.
@@ -475,7 +474,7 @@ $ rails console
 After the console loads, you can use it to work with your application's models:
 
 <shell>
->> p = Post.create(:content => "A new post")
+>> p = Post.new(:content => "A new post")
 => #<Post id: nil, name: nil, title: nil, 
      content: "A new post", created_at: nil,
      updated_at: nil>
@@ -1194,7 +1193,7 @@ The +destroy+ action will find the post we are looking at, locate the comment wi
 
 h4. Deleting Associated Objects
 
-If you delete a post then it's associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to use the +dependent+ option of an association to achieve this. Modify the Post model, +app/models/post.rb+, as follows:
+If you delete a post then its associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to use the +dependent+ option of an association to achieve this. Modify the Post model, +app/models/post.rb+, as follows:
 
 <ruby>
 class Post < ActiveRecord::Base
@@ -1486,6 +1485,7 @@ h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/2
 
+* July 12, 2010: Fixes, editing and updating of code samples by "Jaime Iniesta":http://jaimeiniesta.com
 * May 16, 2010: Added a section on configuration gotchas to address common encoding problems that people might have by "Yehuda Katz":http://www.yehudakatz.com
 * April 30, 2010: Fixes, editing and updating of code samples by "Rohit Arondekar":http://rohitarondekar.com
 * April 25, 2010: Couple of more minor fixups "Mikel Lindsaar":credits.html#raasdnil

railties/guides/source/i18n.textile

@@ -287,7 +287,7 @@ You most probably have something like this in one of your applications:
 
 <ruby>
 # config/routes.rb
-Yourapp::Application.routes.draw do |map|
+Yourapp::Application.routes.draw do
   root :to => "home#index"
 end
 

railties/lib/rails/generators/actions.rb

@@ -40,7 +40,7 @@ def plugin(name, options)
         end
       end
 
-      # Adds an entry into config/environment.rb for the supplied gem. If env
+      # Adds an entry into Gemfile for the supplied gem. If env
       # is specified, add the gem to the given environment.
       #
       # ==== Example
@@ -100,7 +100,7 @@ def add_source(source, options={})
         end
       end
 
-      # Adds a line inside the Initializer block for config/environment.rb.
+      # Adds a line inside the Application class for config/application.rb.
       #
       # If options :env is specified, the line is appended to the corresponding
       # file in config/environments.