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

RELEASING_RAILS.rdoc

@@ -25,10 +25,10 @@ for Rails.  You can check the status of his tests here:
 
 Do not release with Red AWDwR tests.
 
-=== Do we have any git dependencies?  If so, contact those authors.
+=== Do we have any Git dependencies?  If so, contact those authors.
 
-Having git dependencies indicates that we depend on unreleased code.
-Obviously rails cannot be released when it depends on unreleased code.
+Having Git dependencies indicates that we depend on unreleased code.
+Obviously Rails cannot be released when it depends on unreleased code.
 Contact the authors of those particular gems and work out a release date that
 suits them.
 
@@ -115,14 +115,14 @@ what to do in case anything goes wrong:
 === Send Rails release announcements
 
 Write a release announcement that includes the version, changes, and links to
-github where people can find the specific commit list.  Here are the mailing
+GitHub where people can find the specific commit list.  Here are the mailing
 lists where you should announce:
 
 * rubyonrails-core@googlegroups.com
 * rubyonrails-talk@googlegroups.com
 * ruby-talk@ruby-lang.org
 
-Use markdown format for your announcement.  Remember to ask people to report
+Use Markdown format for your announcement.  Remember to ask people to report
 issues with the release candidate to the rails-core mailing list.
 
 IMPORTANT: If any users experience regressions when using the release
@@ -131,16 +131,16 @@ break existing applications.
 
 === Post the announcement to the Rails blog.
 
-If you used markdown format for your email, you can just paste it in to the
+If you used Markdown format for your email, you can just paste it in to the
 blog.
 
 * http://weblog.rubyonrails.org
 
-=== Post the announcement to the Rails twitter account.
+=== Post the announcement to the Rails Twitter account.
 
 == Time between release candidate and actual release
 
-Check the rails-core mailing list and the github issue list for regressions in
+Check the rails-core mailing list and the GitHub issue list for regressions in
 the RC.
 
 If any regressions are found, fix the regressions and repeat the release
@@ -167,7 +167,7 @@ Today, do this stuff in this order:
 * Email security lists
 * Email general announcement lists
 
-=== Emailing the rails security announce list
+=== Emailing the Rails security announce list
 
 Email the security announce list once for each vulnerability fixed.
 

actionpack/lib/action_controller/metal/data_streaming.rb

@@ -76,8 +76,8 @@ def send_file(path, options = {}) #:doc:
       end
 
       # Avoid having to pass an open file handle as the response body.
-      # Rack::Sendfile will usually intercepts the response and just uses
-      # the path directly, so no reason to open the file.
+      # Rack::Sendfile will usually intercept the response and uses
+      # the path directly, so there is no reason to open the file.
       class FileBody #:nodoc:
         attr_reader :to_path
 

actionpack/lib/action_view/helpers/url_helper.rb

@@ -60,11 +60,15 @@ def optimize_routes_generation? #:nodoc:
       #
       # ==== Relying on named routes
       #
-      # Passing a record (like an Active Record) instead of a Hash as the options parameter will
+      # Passing a record (like an Active Record) instead of a hash as the options parameter will
       # trigger the named route for that record. The lookup will happen on the name of the class. So passing a
       # Workshop object will attempt to use the +workshop_path+ route. If you have a nested route, such as
       # +admin_workshop_path+ you'll have to call that explicitly (it's impossible for +url_for+ to guess that route).
       #
+      # ==== Implicit Controller Namespacing
+      #
+      # Controllers passed in using the +:controller+ option will retain their namespace unless it is an absolute one.
+      #
       # ==== Examples
       #   <%= url_for(:action => 'index') %>
       #   # => /blog/
@@ -102,6 +106,14 @@ def optimize_routes_generation? #:nodoc:
       #   <%= url_for(:back) %>
       #   # if request.env["HTTP_REFERER"] is not set or is blank
       #   # => javascript:history.back()
+      #
+      #   <%= url_for(:action => 'index', :controller => 'users') %>
+      #   # Assuming an "admin" namespace
+      #   # => /admin/users
+      #
+      #   <%= url_for(:action => 'index', :controller => '/users') %>
+      #   # Specify absolute path with beginning slash
+      #   # => /users
       def url_for(options = nil)
         case options
         when String

activemodel/lib/active_model/callbacks.rb

@@ -38,6 +38,17 @@ module ActiveModel
   #     # Your code here
   #   end
   #
+  # When defining an around callback remember to yield to the block, otherwise
+  # it won't be executed:
+  #
+  #  around_create :log_status
+  #
+  #  def log_status
+  #    puts 'going to call the block...'
+  #    yield
+  #    puts 'block successfully called.'
+  #  end
+  #
   # You can choose not to have all three callbacks by passing a hash to the
   # +define_model_callbacks+ method.
   #

guides/source/action_controller_overview.textile

@@ -478,9 +478,9 @@ class ChangesController < ActionController::Base
 end
 </ruby>
 
-Note that an around filter wraps also rendering. In particular, if in the example above the view itself reads from the database via a scope or whatever, it will do so within the transaction and thus present the data to preview.
+Note that an around filter also wraps rendering. In particular, if in the example above, the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview.
 
-They can choose not to yield and build the response themselves, in which case the action is not run.
+You can choose not to yield and build the response yourself, in which case the action will not be run.
 
 h4. Other Ways to Use Filters
 

guides/source/action_mailer_basics.textile

@@ -4,7 +4,7 @@ This guide should provide you with all you need to get started in sending and re
 
 endprologue.
 
-WARNING. This Guide is based on Rails 3.2. 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. Introduction
 
@@ -84,7 +84,7 @@ Create a file called +welcome_email.html.erb+ in +app/views/user_mailer/+. This
 </html>
 </erb>
 
-It is also a good idea to make a text part for this email, to do this, create a file called +welcome_email.text.erb+ in +app/views/user_mailer/+:
+It is also a good idea to make a text part for this email. To do this, create a file called +welcome_email.text.erb+ in +app/views/user_mailer/+:
 
 <erb>
 Welcome to example.com, <%= @user.name %>
@@ -144,22 +144,22 @@ The method +welcome_email+ returns a <tt>Mail::Message</tt> object which can the
 
 NOTE: In previous versions of Rails, you would call +deliver_welcome_email+ or +create_welcome_email+. This has been deprecated in Rails 3.0 in favour of just calling the method name itself.
 
-WARNING: Sending out an email should only take a fraction of a second, but if you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job.
+WARNING: Sending out an email should only take a fraction of a second. If you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job.
 
 h4. Auto encoding header values
 
 Action Mailer now handles the auto encoding of multibyte characters inside of headers and bodies.
 
 If you are using UTF-8 as your character set, you do not have to do anything special, just go ahead and send in UTF-8 data to the address fields, subject, keywords, filenames or body of the email and Action Mailer will auto encode it into quoted printable for you in the case of a header field or Base64 encode any body parts that are non US-ASCII.
 
-For more complex examples such as defining alternate character sets or self encoding text first, please refer to the Mail library.
+For more complex examples such as defining alternate character sets or self-encoding text first, please refer to the Mail library.
 
 h4. Complete List of Action Mailer Methods
 
 There are just three methods that you need to send pretty much any email message:
 
-* <tt>headers</tt> - Specifies any header on the email you want, you can pass a hash of header field names and value pairs, or you can call <tt>headers[:field_name] = 'value'</tt>
-* <tt>attachments</tt> - Allows you to add attachments to your email, for example <tt>attachments['file-name.jpg'] = File.read('file-name.jpg')</tt>
+* <tt>headers</tt> - Specifies any header on the email you want. You can pass a hash of header field names and value pairs, or you can call <tt>headers[:field_name] = 'value'</tt>.
+* <tt>attachments</tt> - Allows you to add attachments to your email. For example, <tt>attachments['file-name.jpg'] = File.read('file-name.jpg')</tt>.
 * <tt>mail</tt> - Sends the actual email itself. You can pass in headers as a hash to the mail method as a parameter, mail will then create an email, either plain text, or multipart, depending on what email templates you have defined.
 
 h5. Custom Headers
@@ -184,7 +184,7 @@ headers["X-Spam"] = value
 headers {"X-Spam" => value, "X-Special" => another_value}
 </ruby>
 
-TIP: All <tt>X-Value</tt> headers per the RFC2822 can appear more than one time. If you want to delete an <tt>X-Value</tt> header, you need to assign it a value of <tt>nil</tt>.
+TIP: All <tt>X-Value</tt> headers per the RFC2822 can appear more than once. If you want to delete an <tt>X-Value</tt> header, you need to assign it a value of <tt>nil</tt>.
 
 h5. Adding Attachments
 
@@ -196,7 +196,7 @@ Adding attachments has been simplified in Action Mailer 3.0.
 attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
 </ruby>
 
-NOTE: Mail will automatically Base64 encode an attachment, if you want something different, pre-encode your content and pass in the encoded content and encoding in a +Hash+ to the +attachments+ method.
+NOTE: Mail will automatically Base64 encode an attachment. If you want something different, pre-encode your content and pass in the encoded content and encoding in a +Hash+ to the +attachments+ method.
 
 * Pass the file name and specify headers and content and Action Mailer and Mail will use the settings you pass in.
 
@@ -229,7 +229,7 @@ end
 <%= image_tag attachments['image.jpg'].url %>
 </erb>
 
-* As this is a standard call to +image_tag+ you can pass in an options hash after the attachment url as you could for any other image:
+* As this is a standard call to +image_tag+ you can pass in an options hash after the attachment URL as you could for any other image:
 
 <erb>
 <p>Hello there, this is our image</p>
@@ -240,7 +240,7 @@ end
 
 h5. Sending Email To Multiple Recipients
 
-It is possible to send email to one or more recipients in one email (for e.g. informing all admins of a new signup) by setting the list of emails to the <tt>:to</tt> key. The list of emails can be an array of email addresses or a single string with the addresses separated by commas.
+It is possible to send email to one or more recipients in one email (e.g., informing all admins of a new signup) by setting the list of emails to the <tt>:to</tt> key. The list of emails can be an array of email addresses or a single string with the addresses separated by commas.
 
 <ruby>
 class AdminMailer < ActionMailer::Base
@@ -458,6 +458,7 @@ The following configuration options are best made in one of the environment file
 |+perform_deliveries+|Determines whether deliveries are actually carried out when the +deliver+ method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing.|
 |+deliveries+|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.|
 |+async+|Setting this flag will turn on asynchronous message sending, message rendering and delivery will be pushed to <tt>Rails.queue</tt> for processing.|
+|+default_options+|Allows you to set default values for the <tt>mail</tt> method options (<tt>:from</tt>, <tt>:reply_to</tt>, etc.).|
 
 h4. Example Action Mailer Configuration
 
@@ -472,6 +473,7 @@ config.action_mailer.delivery_method = :sendmail
 # }
 config.action_mailer.perform_deliveries = true
 config.action_mailer.raise_delivery_errors = true
+config.action_mailer.default_options = {from: "no-replay@example.org"}
 </ruby>
 
 h4. Action Mailer Configuration for GMail

guides/source/active_model_basics.textile

@@ -1,18 +1,18 @@
 h2. Active Model Basics
 
-This guide should provide you with all you need to get started using model classes. Active Model allow for Action Pack helpers to interact with non-ActiveRecord models. Active Model also helps building custom ORMs for use outside of the Rails framework.
+This guide should provide you with all you need to get started using model classes. Active Model allows for Action Pack helpers to interact with non-ActiveRecord models. Active Model also helps building custom ORMs for use outside of the Rails framework.
 
 endprologue.
 
-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.0. Some of the code shown here will not work in earlier versions of Rails.
 
 h3. Introduction
 
-Active Model is a library containing various modules used in developing frameworks that need to interact with the Rails Action Pack library. Active Model provides a known set of interfaces for usage in classes. Some of modules are explained below -  
+Active Model is a library containing various modules used in developing frameworks that need to interact with the Rails Action Pack library. Active Model provides a known set of interfaces for usage in classes. Some of modules are explained below.  
 
 h4. AttributeMethods
 
-AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes, which methods on the object will use them.
+The AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes, which methods on the object will use them.
 
 <ruby>
 class Person
@@ -92,7 +92,7 @@ person.to_param            #=> nil
 
 h4. Dirty
 
-An object becomes dirty when an object is gone through one or more changes to its attributes and not yet saved. This gives the ability to check whether an object has been changed or not. It also has attribute based accessor methods. Lets consider a Person class with attributes first_name and last_name
+An object becomes dirty when it has gone through one or more changes to its attributes and has not been saved. This gives the ability to check whether an object has been changed or not. It also has attribute based accessor methods. Let's consider a Person class with attributes first_name and last_name
 
 <ruby>
 require 'active_model'
@@ -168,7 +168,7 @@ Track what was the previous value of the attribute.
 person.first_name_was  #=> "First Name"
 </ruby>
 
-Track  both previous and current value of the changed attribute. Returns an array if changed else returns nil
+Track both previous and current value of the changed attribute. Returns an array if changed, else returns nil.
 
 <ruby>
 #attr_name_change

guides/source/active_record_querying.textile

@@ -53,6 +53,7 @@ To retrieve objects from the database, Active Record provides several finder met
 The methods are:
 * +bind+
 * +create_with+
+* +eager_load+
 * +extending+
 * +from+
 * +group+
@@ -61,9 +62,11 @@ The methods are:
 * +joins+
 * +limit+
 * +lock+
+* +none+
 * +offset+
 * +order+
 * +none+
+* +preload+
 * +readonly+
 * +references+
 * +reorder+

guides/source/api_documentation_guidelines.textile

@@ -127,7 +127,7 @@ class Array
 end
 </ruby>
 
-WARNING: Using a pair of +&#43;...&#43;+ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w&#43;\z</tt>. For anything else  use +&lt;tt&gt;...&lt;/tt&gt;+, notably symbols, setters, inline snippets, etc:
+WARNING: Using a pair of +&#43;...&#43;+ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w&#43;\z</tt>. For anything else  use +&lt;tt&gt;...&lt;/tt&gt;+, notably symbols, setters, inline snippets, etc.
 
 h4. Regular Font
 

guides/source/asset_pipeline.textile

@@ -443,6 +443,8 @@ If you have other manifests or individual stylesheets and JavaScript files to in
 config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js']
 </erb>
 
+NOTE. Always specify an expected compiled filename that ends with js or css, even if you want to add Sass or CoffeeScript files to the precompile array.
+
 The rake task also generates a +manifest.yml+ that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets. A typical manifest file looks like:
 
 <plain>

guides/source/caching_with_rails.textile

@@ -33,7 +33,7 @@ class ProductsController < ActionController
   caches_page :index
 
   def index
-    @products = Products.all
+    @products = Product.all
   end
 end
 </ruby>
@@ -52,7 +52,7 @@ class ProductsController < ActionController
   caches_page :index
 
   def index
-    @products = Products.all
+    @products = Product.all
   end
 
   def create