Merge branch 'master' of github.com:lifo/docrails

actionpack/lib/action_dispatch/routing/url_for.rb

@@ -68,7 +68,7 @@ module Routing
     # This generates, among other things, the method <tt>users_path</tt>. By default,
     # this method is accessible from your controllers, views and mailers. If you need
     # to access this auto-generated method from other places (such as a model), then
-    # you can do that by including ActionController::UrlFor in your class:
+    # you can do that by including Rails.application.routes.url_helpers in your class:
     #
     #   class User < ActiveRecord::Base
     #     include Rails.application.routes.url_helpers

actionpack/lib/action_view/helpers/form_options_helper.rb

@@ -288,38 +288,55 @@ def time_zone_select(object, method, priority_zones = nil, options = {}, html_op
       #
       # Examples (call, result):
       #   options_for_select([["Dollar", "$"], ["Kroner", "DKK"]])
-      #     <option value="$">Dollar</option>\n<option value="DKK">Kroner</option>
+      #   # <option value="$">Dollar</option>
+      #   # <option value="DKK">Kroner</option>
       #
       #   options_for_select([ "VISA", "MasterCard" ], "MasterCard")
-      #     <option>VISA</option>\n<option selected="selected">MasterCard</option>
+      #   # <option>VISA</option>
+      #   # <option selected="selected">MasterCard</option>
       #
       #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
-      #     <option value="$20">Basic</option>\n<option value="$40" selected="selected">Plus</option>
+      #   # <option value="$20">Basic</option>
+      #   # <option value="$40" selected="selected">Plus</option>
       #
       #   options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"])
-      #     <option selected="selected">VISA</option>\n<option>MasterCard</option>\n<option selected="selected">Discover</option>
+      #   # <option selected="selected">VISA</option>
+      #   # <option>MasterCard</option>
+      #   # <option selected="selected">Discover</option>
       #
       # You can optionally provide html attributes as the last element of the array.
       #
       # Examples:
       #   options_for_select([ "Denmark", ["USA", {:class => 'bold'}], "Sweden" ], ["USA", "Sweden"])
-      #     <option value="Denmark">Denmark</option>\n<option value="USA" class="bold" selected="selected">USA</option>\n<option value="Sweden" selected="selected">Sweden</option>
+      #   # <option value="Denmark">Denmark</option>
+      #   # <option value="USA" class="bold" selected="selected">USA</option>
+      #   # <option value="Sweden" selected="selected">Sweden</option>
       #
       #   options_for_select([["Dollar", "$", {:class => "bold"}], ["Kroner", "DKK", {:onclick => "alert('HI');"}]])
-      #     <option value="$" class="bold">Dollar</option>\n<option value="DKK" onclick="alert('HI');">Kroner</option>
+      #   # <option value="$" class="bold">Dollar</option>
+      #   # <option value="DKK" onclick="alert('HI');">Kroner</option>
       #
       # If you wish to specify disabled option tags, set +selected+ to be a hash, with <tt>:disabled</tt> being either a value
       # or array of values to be disabled. In this case, you can use <tt>:selected</tt> to specify selected option tags.
       #
       # Examples:
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :disabled => "Super Platinum")
-      #     <option value="Free">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # <option value="Free">Free</option>
+      #   # <option value="Basic">Basic</option>
+      #   # <option value="Advanced">Advanced</option>
+      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :disabled => ["Advanced", "Super Platinum"])
-      #     <option value="Free">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced" disabled="disabled">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # <option value="Free">Free</option>
+      #   # <option value="Basic">Basic</option>
+      #   # <option value="Advanced" disabled="disabled">Advanced</option>
+      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :selected => "Free", :disabled => "Super Platinum")
-      #     <option value="Free" selected="selected">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   # <option value="Free" selected="selected">Free</option>
+      #   # <option value="Basic">Basic</option>
+      #   # <option value="Advanced">Advanced</option>
+      #   # <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
       def options_for_select(container, selected = nil)

actionpack/lib/action_view/helpers/form_tag_helper.rb

@@ -45,7 +45,7 @@ module FormTagHelper
       #   # => <form action="/posts" method="post">
       #
       #   form_tag('/posts/1', :method => :put)
-      #   # => <form action="/posts/1" method="put">
+      #   # => <form action="/posts/1" method="post"> ... <input name="_method" type="hidden" value="put" /> ...
       #
       #   form_tag('/upload', :multipart => true)
       #   # => <form action="/upload" method="post" enctype="multipart/form-data">

actionpack/lib/action_view/helpers/text_helper.rb

@@ -45,7 +45,7 @@ module TextHelper
       #       if logged_in
       #         concat "Logged in!"
       #       else
-      #         concat link_to('login', :action => login)
+      #         concat link_to('login', :action => :login)
       #       end
       #       # will either display "Logged in!" or a login link
       #   %>

activemodel/README.rdoc

@@ -25,7 +25,7 @@ to integrate with Action Pack out of the box: <tt>ActiveModel::Model</tt>.
 
     person = Person.new(:name => 'bob', :age => '18')
     person.name # => 'bob'
-    person.age # => 18
+    person.age # => '18'
     person.valid? # => true
 
 It includes model name introspections, conversions, translations and

activerecord/lib/active_record/aggregations.rb

@@ -86,6 +86,12 @@ def clear_aggregation_cache #:nodoc:
     #   customer.address_street = "Hyancintvej"
     #   customer.address_city   = "Copenhagen"
     #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
+    #
+    #   customer.address_street = "Vesterbrogade"
+    #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
+    #   customer.clear_aggregation_cache
+    #   customer.address        # => Address.new("Vesterbrogade", "Copenhagen")
+    #
     #   customer.address = Address.new("May Street", "Chicago")
     #   customer.address_street # => "May Street"
     #   customer.address_city   # => "Chicago"
@@ -101,8 +107,8 @@ def clear_aggregation_cache #:nodoc:
     # ActiveRecord::Base classes are entity objects.
     #
     # It's also important to treat the value objects as immutable. Don't allow the Money object to have
-    # its amount changed after creation. Create a new Money object with the new value instead. This
-    # is exemplified by the Money#exchange_to method that returns a new value object instead of changing
+    # its amount changed after creation. Create a new Money object with the new value instead. The
+    # Money#exchange_to method is an example of this. It returns a new value object instead of changing
     # its own values. Active Record won't persist value objects that have been changed through means
     # other than the writer method.
     #
@@ -119,7 +125,7 @@ def clear_aggregation_cache #:nodoc:
     # option, as arguments. If the value class doesn't support this convention then +composed_of+ allows
     # a custom constructor to be specified.
     #
-    # When a new value is assigned to the value object the default assumption is that the new value
+    # When a new value is assigned to the value object, the default assumption is that the new value
     # is an instance of the value class. Specifying a custom converter allows the new value to be automatically
     # converted to an instance of value class if necessary.
     #

activerecord/lib/active_record/associations.rb

@@ -1129,7 +1129,7 @@ module ClassMethods
       #   it would skip the first 4 rows.
       # [:select]
       #   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 but not include the joined columns. Do not forget
+      #   you want to do a join but not include the joined columns, for example. Do not forget
       #   to include the primary and foreign keys, otherwise it will raise an error.
       # [:as]
       #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
@@ -1264,8 +1264,8 @@ def has_many(name, options = {}, &extension)
       # [:as]
       #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
       # [:select]
-      #   By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if, for example,
-      #   you want to do a join but not include the joined columns. Do not forget to include the
+      #   By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if
+      #   you want to do a join but not include the joined columns, for example. Do not forget to include the
       #   primary and foreign keys, otherwise it will raise an error.
       # [:through]
       #   Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt>,
@@ -1355,7 +1355,7 @@ def has_one(name, options = {})
       #   SQL fragment, such as <tt>authorized = 1</tt>.
       # [:select]
       #   By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed
-      #   if, for example, you want to do a join but not include the joined columns. Do not
+      #   if you want to do a join but not include the joined columns, for example. Do not
       #   forget to include the primary and foreign keys, otherwise it will raise an error.
       # [:foreign_key]
       #   Specify the foreign key used for the association. By default this is guessed to be the name
@@ -1382,7 +1382,7 @@ def has_one(name, options = {})
       #   and +decrement_counter+. The counter cache is incremented when an object of this
       #   class is created and decremented when it's destroyed. This requires that a column
       #   named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging Comment class)
-      #   is used on the associate class (such as a Post class) - that is the migration for 
+      #   is used on the associate class (such as a Post class) - that is the migration for
       #   <tt>#{table_name}_count</tt> is created on the associate class (such that Post.comments_count will
       #   return the count cached, see note below). You can also specify a custom counter
       #   cache column by providing a column name instead of a +true+/+false+ value to this
@@ -1432,7 +1432,7 @@ def belongs_to(name, options = {})
       # Specifies a many-to-many relationship with another class. This associates two classes via an
       # intermediate join table. Unless the join table is explicitly specified as an option, it is
       # guessed using the lexical order of the class names. So a join between Developer and Project
-      # will give the default join table name of "developers_projects" because "D" outranks "P".
+      # will give the default join table name of "developers_projects" because "D" precedes "P" alphabetically.
       # Note that this precedence is calculated using the <tt><</tt> 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
@@ -1576,8 +1576,8 @@ def belongs_to(name, options = {})
       #   An integer determining the offset from where the rows should be fetched. So at 5,
       #   it would skip the first 4 rows.
       # [:select]
-      #   By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if, for example,
-      #   you want to do a join but not include the joined columns. Do not forget to include the primary
+      #   By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if
+      #   you want to do a join but exclude the joined columns, for example. Do not forget to include the primary
       #   and foreign keys, otherwise it will raise an error.
       # [:readonly]
       #   If true, all the associated objects are readonly through the association.

activerecord/lib/active_record/relation/calculations.rb

@@ -144,7 +144,7 @@ def pluck(column_name)
     # Examples:
     #
     #   Person.ids # SELECT people.id FROM people
-    #   Person.joins(:companies).ids # SELECT people.id FROM PEOPLE INNER JOIN companies ON companies.person_id = people.id
+    #   Person.joins(:companies).ids # SELECT people.id FROM people INNER JOIN companies ON companies.person_id = people.id
     def ids
       pluck primary_key
     end

guides/code/getting_started/app/controllers/comments_controller.rb

@@ -1,16 +1,17 @@
 class CommentsController < ApplicationController
 	http_basic_authenticate_with :name => "dhh", :password => "secret", :only => :destroy
+
   def create
     @post = Post.find(params[:post_id])
     @comment = @post.comments.create(params[:comment])
     redirect_to post_path(@post)
   end
- 
+
   def destroy
     @post = Post.find(params[:post_id])
     @comment = @post.comments.find(params[:id])
     @comment.destroy
     redirect_to post_path(@post)
   end
- 
+
 end

guides/code/getting_started/app/controllers/posts_controller.rb

@@ -1,5 +1,7 @@
 class PostsController < ApplicationController
 
+  http_basic_authenticate_with :name => "dhh", :password => "secret", :except => [:index, :show]
+
   def index
     @posts = Post.all
   end

guides/code/getting_started/app/views/comments/_comment.html.erb

@@ -1,13 +1,13 @@
 <p>
-  <b>Commenter:</b>
+  <strong>Commenter:</strong>
   <%= comment.commenter %>
 </p>
- 
+
 <p>
-  <b>Comment:</b>
+  <strong>Comment:</strong>
   <%= comment.body %>
 </p>
- 
+
 <p>
   <%= link_to 'Destroy Comment', [comment.post, comment],
                :confirm => 'Are you sure?',

guides/code/getting_started/app/views/comments/_form.html.erb

@@ -1,13 +1,13 @@
 <%= form_for([@post, @post.comments.build]) do |f| %>
-  <div class="field">
+  <p>
     <%= f.label :commenter %><br />
     <%= f.text_field :commenter %>
-  </div>
-  <div class="field">
+  </p>
+  <p>
     <%= f.label :body %><br />
     <%= f.text_area :body %>
-  </div>
-  <div class="actions">
+  </p>
+  <p>
     <%= f.submit %>
-  </div>
+  </p>
 <% end %>

guides/code/getting_started/app/views/posts/show.html.erb

@@ -8,21 +8,11 @@
   <%= @post.text %>
 </p>
 
+<h2>Comments</h2>
+<%= render @post.comments %>
 
 <h2>Add a comment:</h2>
-<%= form_for([@post, @post.comments.build]) do |f| %>
-  <p>
-    <%= f.label :commenter %><br />
-    <%= f.text_field :commenter %>
-  </p>
-  <p>
-    <%= f.label :body %><br />
-    <%= f.text_area :body %>
-  </p>
-  <p>
-    <%= f.submit %>
-  </p>
-<% end %>
+<%= render "comments/form" %>
 
 <%= link_to 'Edit Post', edit_post_path(@post) %> |
 <%= link_to 'Back to Posts', posts_path %>

guides/source/asset_pipeline.textile

@@ -204,6 +204,8 @@ Images can also be organized into subdirectories if required, and they can be ac
 <%= image_tag "icons/rails.png" %>
 </erb>
 
+WARNING: If you're precompiling your assets (see "In Production":#in-production below), linking to an asset that does not exist will raise an exception in the calling page. This includes linking to a blank string. As such, be careful using <tt>image_tag</tt> and the other helpers with user-supplied data.
+
 h5. CSS and ERB
 
 The asset pipeline automatically evaluates ERB. This means that if you add an +erb+ extension to a CSS asset (for example, +application.css.erb+), then helpers like +asset_path+ are available in your CSS rules:

guides/source/command_line.textile

@@ -12,7 +12,7 @@ endprologue.
 
 NOTE: This tutorial assumes you have basic Rails knowledge from reading the "Getting Started with Rails Guide":getting_started.html.
 
-WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails.
+WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails.
 
 h3. Command Line Basics
 
@@ -31,7 +31,7 @@ h4. +rails new+
 
 The first thing we'll want to do is create a new Rails application by running the +rails new+ command after installing Rails.
 
-WARNING: You can install the rails gem by typing +gem install rails+, if you don't have it already. Follow the instructions in the "Rails 3 Release Notes":/3_0_release_notes.html
+TIP: You can install the rails gem by typing +gem install rails+, if you don't have it already.
 
 <shell>
 $ rails new commandsapp
@@ -185,8 +185,6 @@ $ rails server
 => Booting WEBrick...
 </shell>
 
-WARNING: Make sure that you do not have any "tilde backup" files in +app/views/(controller)+, or else WEBrick will _not_ show the expected output. This seems to be a *bug* in Rails 2.3.0.
-
 The URL will be "http://localhost:3000/greetings/hello":http://localhost:3000/greetings/hello.
 
 INFO: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the *index* action of that controller.

guides/source/configuring.textile

@@ -248,14 +248,6 @@ They can also be removed from the stack completely:
 config.middleware.delete ActionDispatch::BestStandardsSupport
 </ruby>
 
-In addition to these methods to handle the stack, if your application is going to be used as an API endpoint only, the middleware stack can be configured like this:
-
-<ruby>
-config.middleware.http_only!
-</ruby>
-
-By doing this, Rails will create a smaller middleware stack, by not adding some middlewares that are usually useful for browser access only, such as Cookies, Session and Flash, BestStandardsSupport, and MethodOverride. You can always add any of them later manually if you want. Refer to the "API App docs":api_app.html for more info on how to setup your application for API only apps.
-
 h4. Configuring i18n
 
 * +config.i18n.default_locale+ sets the default locale of an application used for i18n. Defaults to +:en+.