Merge remote branch 'docrails/master'

actionpack/lib/action_view/helpers/form_helper.rb

@@ -213,12 +213,22 @@ module FormHelper
       #     ...
       #   <% end %>
       #
-      # And for namespaced routes, like +admin_post_url+:
+      # For namespaced routes, like +admin_post_url+:
       #
       #   <%= form_for([:admin, @post]) do |f| %>
       #    ...
       #   <% end %>
       #
+      # If your resource has associations defined, for example, you want to add comments 
+      # to the post given that the routes are set correctly:
+      #
+      #   <%= form_for([@document, @comment]) do |f| %>
+      #    ...
+      #   <% end %>
+      #
+      # Where +@document = Document.find(params[:id])+ and
+      # +@comment = Comment.new+.
+      #
       # === Unobtrusive JavaScript
       #
       # Specifying:

activerecord/lib/active_record/associations.rb

@@ -763,6 +763,8 @@ module ClassMethods
       #   An empty array is returned if none are found.
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
+      #   Note that this operation instantly fires update sql without waiting for the save or update call on the 
+      #   parent object.
       # [collection.delete(object, ...)]
       #   Removes one or more objects from the collection by setting their foreign keys to +NULL+.
       #   Objects will be in addition destroyed if they're associated with <tt>:dependent => :destroy</tt>,
@@ -1193,6 +1195,8 @@ def belongs_to(association_id, options = {})
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by creating associations in the join table
       #   (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method).
+      #   Note that this operation instantly fires update sql without waiting for the save or update call on the 
+      #   parent object.
       # [collection.delete(object, ...)]
       #   Removes one or more objects from the collection by removing their associations from the join table.
       #   This does not destroy the objects.

activerecord/lib/active_record/base.rb

@@ -869,15 +869,17 @@ def ===(object)
       # Returns the base AR subclass that this class descends from. If A
       # extends AR::Base, A.base_class will return A. If B descends from A
       # through some arbitrarily deep hierarchy, B.base_class will return A.
+      #
+      # If B < A and C < B and if A is an abstract_class then both B.base_class
+      # and C.base_class would return B as the answer since A is an abstract_class.
       def base_class
         class_of_active_record_descendant(self)
       end
 
       # Set this to true if this is an abstract class (see <tt>abstract_class?</tt>).
       attr_accessor :abstract_class
 
-      # Returns whether this class is a base AR class.  If A is a base class and
-      # B descends from A, then B.base_class will return B.
+      # Returns whether this class is an abstract class or not.
       def abstract_class?
         defined?(@abstract_class) && @abstract_class == true
       end

railties/README

@@ -29,13 +29,13 @@ link:files/vendor/rails/actionpack/README.html.
 == Getting Started
 
 1. At the command prompt, create a new Rails application:
-       <tt>rails myapp</tt> (where <tt>myapp</tt> is the application name)
+       <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name)
 
 2. Change directory to <tt>myapp</tt> and start the web server:
        <tt>cd myapp; rails server</tt> (run with --help for options)
 
 3. Go to http://localhost:3000/ and you'll see:
-       "Welcome aboard: You're riding the Rails!"
+       "Welcome aboard: You're riding Ruby on Rails!"
 
 4. Follow the guidelines to start developing your application. You can find 
 the following resources handy:

railties/guides/source/3_0_release_notes.textile

@@ -339,7 +339,9 @@ h5. Other Changes
 * You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the HTML output.
 * Added +grouped_collection_select+ helper to Action View.
 * +content_for?+ has been added allowing you to check for the existence of content in a view before rendering.
-
+* passing +:value => nil+ to form helpers will set the field's +value+ attribute to nil as opposed to using the default value
+* passing +:id => nil+ to form helpers will cause those fields to be rendered with no +id+ attribute
+* passing +:alt => nil+ to +image_tag+ will cause the +img+ tag to render with no +alt+ attribute
 
 h3. Active Model
 

railties/guides/source/active_record_validations_callbacks.textile

@@ -86,9 +86,9 @@ The following methods skip validations, and will save the object to the database
 * +update_attribute+
 * +update_counters+
 
-Note that +save+ also has the ability to skip validations if passed +false+ as argument. This technique should be used with caution.
+Note that +save+ also has the ability to skip validations if passed +:validate => false+ as argument. This technique should be used with caution.
 
-* +save(false)+
+* +save(:validate => false)+
 
 h4. +valid?+ and +invalid?+
 

railties/guides/source/getting_started.textile

@@ -958,7 +958,7 @@ You'll see a bit more complexity here than you did in the controller for posts.
 
 In addition, the code takes advantage of some of the methods available for an association. We use the +create+ method on +@post.comments+ to create and save the comment. This will automatically link the comment so that it belongs to that particular post.
 
-Once we have made the new comment, we send the user back to the original post using the +post_path(@post)+ helper. As we have already seen, this calls the +show+ action of the +PostsController+ which in turn renders the +show.html.erb+ template. This is where we want the comment to show, so let's add that to the +app/view/posts/show.html.erb+.
+Once we have made the new comment, we send the user back to the original post using the +post_path(@post)+ helper. As we have already seen, this calls the +show+ action of the +PostsController+ which in turn renders the +show.html.erb+ template. This is where we want the comment to show, so let's add that to the +app/views/posts/show.html.erb+.
 
 <erb>
 <p class="notice"><%= notice %></p>

railties/guides/source/routing.textile

@@ -382,6 +382,12 @@ match ':controller/:action/:id/:user_id'
 
 An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+.
 
+NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g:
+
+<ruby>
+match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/
+</ruby>
+
 h4. Static Segments
 
 You can specify static segments when creating a route:
@@ -645,31 +651,31 @@ scope :path_names => { :new => "make" } do
 end
 </ruby>
 
-h4. Overriding the Named Helper Prefix
+h4. Prefixing the Named Route Helpers
 
-You can use the :name_prefix option to add a prefix to the named route helpers that Rails generates for a route. You can use this option to prevent collisions between routes using a path scope.
+You can use the +:as+ option to prefix the named route helpers that Rails generates for a route. Use this option to prevent name collisions between routes using a path scope.
 
 <ruby>
 scope "admin" do
-  resources :photos, :name_prefix => "admin"
+  resources :photos, :as => "admin_photos"
 end
 
 resources :photos
 </ruby>
 
 This will provide route helpers such as +admin_photos_path+, +new_admin_photo_path+ etc.
 
-You could specify a name prefix to use for a group of routes in the scope:
+To prefix a group of routes, use +:as+ with +scope+:
 
 <ruby>
-scope "admin", :name_prefix => "admin" do
+scope "admin", :as => "admin" do
   resources :photos, :accounts
 end
 
 resources :photos, :accounts
 </ruby>
 
-NOTE: The +namespace+ scope will automatically add a +:name_prefix+ as well as +:module+ and +:path+ prefixes.
+NOTE: The +namespace+ scope will automatically add +:as+ as well as +:module+ and +:path+ prefixes.
 
 h4. Restricting the Routes Created
 
@@ -714,21 +720,21 @@ Rails now creates routes to the +CategoriesControlleR+.
 
 h4. Overriding the Singular Form
 
-If you want to customize the singular name of the route in the named helpers, you can use the +:singular+ option.
+If you want to define the singular form of a resource, you should add additional rules to the +Inflector+.
 
 <ruby>
-resources :teeth, :singular => "tooth"
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.irregular 'tooth', 'teeth'
+end
 </ruby>
 
-TIP: If you want to define the singular form of a word for your entire application, you should add additional rules to the +Inflector+ instead.
-
-h4(#nested-name-prefix). Using +:name_prefix+ in Nested Resources
+h4(#nested-names). Using +:as+ in Nested Resources
 
-The +:name_prefix+ option overrides the automatically-generated prefix for the parent resource in nested route helpers. For example,
+The +:as+ option overrides the automatically-generated name for the resource in nested route helpers. For example,
 
 <ruby>
 resources :magazines do
-  resources :ads, :name_prefix => 'periodical'
+  resources :ads, :as => 'periodical_ads'
 end
 </ruby>
 

railties/lib/rails/generators/actions.rb

@@ -267,7 +267,7 @@ def freeze!(args={})
         ActiveSupport::Deprecation.warn "freeze! is deprecated since your rails app now comes bundled with Rails by default, please check your Gemfile"
       end
 
-      # Make an entry in Rails routing file conifg/routes.rb
+      # Make an entry in Rails routing file config/routes.rb
       #
       # === Example
       #

railties/lib/rails/generators/rails/app/templates/README

@@ -35,7 +35,7 @@ link:files/vendor/rails/actionpack/README.html.
        <tt>cd myapp; rails server</tt> (run with --help for options)
 
 3. Go to http://localhost:3000/ and you'll see:
-       "Welcome aboard: You're riding the Rails!"
+       "Welcome aboard: You're riding Ruby on Rails!"
 
 4. Follow the guidelines to start developing your application. You can find
 the following resources handy: