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

Author: vijaydev

actionpack/lib/action_view/helpers/form_helper.rb

@@ -775,8 +775,8 @@ def label(object_name, method, content_or_options = nil, options = nil, &block)
       #   text_field(:post, :title, class: "create_input")
       #   # => <input type="text" id="post_title" name="post[title]" value="#{@post.title}" class="create_input" />
       #
-      #   text_field(:session, :user, onchange: "if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }")
-      #   # => <input type="text" id="session_user" name="session[user]" value="#{@session.user}" onchange = "if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }"/>
+      #   text_field(:session, :user, onchange: "if $('#session_user').value == 'admin' { alert('Your login can not be admin!'); }")
+      #   # => <input type="text" id="session_user" name="session[user]" value="#{@session.user}" onchange = "if $('#session_user').value == 'admin' { alert('Your login can not be admin!'); }"/>
       #
       #   text_field(:snippet, :code, size: 20, class: 'code_input')
       #   # => <input type="text" id="snippet_code" name="snippet[code]" size="20" value="#{@snippet.code}" class="code_input" />
@@ -830,13 +830,25 @@ def hidden_field(object_name, method, options = {})
       #
       # Using this method inside a +form_for+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
       #
+      # ==== Options
+      # * Creates standard HTML attributes for the tag.
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * <tt>:multiple</tt> - If set to true, *in most updated browsers* the user will be allowed to select multiple files.
+      # * <tt>:accept</tt> - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations.
+      #
       # ==== Examples
       #   file_field(:user, :avatar)
       #   # => <input type="file" id="user_avatar" name="user[avatar]" />
       #
+      #   file_field(:post, :image, :multiple => true)
+      #   # => <input type="file" id="post_image" name="post[image]" multiple="true" />
+      #
       #   file_field(:post, :attached, accept: 'text/html')
       #   # => <input accept="text/html" type="file" id="post_attached" name="post[attached]" />
       #
+      #   file_field(:post, :image, accept: 'image/png,image/gif,image/jpeg')
+      #   # => <input type="file" id="post_image" name="post[image]" accept="image/png,image/gif,image/jpeg" />
+      #
       #   file_field(:attachment, :file, class: 'file_input')
       #   # => <input type="file" id="attachment_file" name="attachment[file]" class="file_input" />
       def file_field(object_name, method, options = {})
@@ -1214,6 +1226,10 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
         RUBY_EVAL
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def fields_for(record_name, record_object = nil, fields_options = {}, &block)
         fields_options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options?
         fields_options[:builder] ||= options[:builder]
@@ -1243,23 +1259,43 @@ def fields_for(record_name, record_object = nil, fields_options = {}, &block)
         @template.fields_for(record_name, record_object, fields_options, &block)
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def label(method, text = nil, options = {}, &block)
         @template.label(@object_name, method, text, objectify_options(options), &block)
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
         @template.check_box(@object_name, method, objectify_options(options), checked_value, unchecked_value)
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def radio_button(method, tag_value, options = {})
         @template.radio_button(@object_name, method, tag_value, objectify_options(options))
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def hidden_field(method, options = {})
         @emitted_hidden_id = true if method == :id
         @template.hidden_field(@object_name, method, objectify_options(options))
       end
 
+      # Instructions for this +method+ can be found in this documentation.
+      # For reusability and delegation reasons, various +methods+ have equal names.
+      # Please, look up the next +method+ with this name
+      #
       def file_field(method, options = {})
         self.multipart = true
         @template.file_field(@object_name, method, objectify_options(options))

actionpack/lib/action_view/helpers/form_tag_helper.rb

@@ -233,6 +233,8 @@ def hidden_field_tag(name, value = nil, options = {})
       # ==== Options
       # * Creates standard HTML attributes for the tag.
       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * <tt>:multiple</tt> - If set to true, *in most updated browsers* the user will be allowed to select multiple files.
+      # * <tt>:accept</tt> - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations.
       #
       # ==== Examples
       #   file_field_tag 'attachment'

activesupport/lib/active_support/deprecation/proxy_wrappers.rb

@@ -30,7 +30,7 @@ def method_missing(called, *args, &block)
     #   @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!")
     #   @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!", deprecator_instance)
     #
-    # When someone execute any method expect +inspect+ on proxy object this will
+    # When someone executes any method except +inspect+ on proxy object this will
     # trigger +warn+ method on +deprecator_instance+.
     #
     # Default deprecator is <tt>ActiveSupport::Deprecation</tt>

guides/source/action_controller_overview.md

@@ -5,13 +5,13 @@ In this guide you will learn how controllers work and how they fit into the requ
 
 After reading this guide, you will know:
 
-* Follow the flow of a request through a controller.
-* Understand why and how to store data in the session or cookies.
-* Work with filters to execute code during request processing.
-* Use Action Controller's built-in HTTP authentication.
-* Stream data directly to the user's browser.
-* Filter sensitive parameters so they do not appear in the application's log.
-* Deal with exceptions that may be raised during request processing.
+* How to follow the flow of a request through a controller.
+* Why and how to store data in the session or cookies.
+* How to work with filters to execute code during request processing.
+* How to use Action Controller's built-in HTTP authentication.
+* How to stream data directly to the user's browser.
+* How to filter sensitive parameters so they do not appear in the application's log.
+* How to deal with exceptions that may be raised during request processing.
 
 --------------------------------------------------------------------------------
 
@@ -849,15 +849,15 @@ NOTE: Certain exceptions are only rescuable from the `ApplicationController` cla
 Force HTTPS protocol
 --------------------
 
-Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. Since Rails 3.1 you can now use the `force_ssl` method in your controller to enforce that:
+Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. You can use the `force_ssl` method in your controller to enforce that:
 
 ```ruby
 class DinnerController
   force_ssl
 end
 ```
 
-Just like the filter, you could also passing `:only` and `:except` to enforce the secure connection only to specific actions:
+Just like the filter, you could also pass `:only` and `:except` to enforce the secure connection only to specific actions:
 
 ```ruby
 class DinnerController

guides/source/action_mailer_basics.md

@@ -5,6 +5,10 @@ This guide should provide you with all you need to get started in sending and re
 
 After reading this guide, you will know:
 
+* How to send and receive email within a Rails application.
+* How to generate and edit an Action Mailer class and mailer view.
+* How to configure Action Mailer for your environment.
+* How to test your Action Mailer classes.
 --------------------------------------------------------------------------------
 
 Introduction
@@ -105,7 +109,7 @@ When you call the `mail` method now, Action Mailer will detect the two templates
 
 #### Wire It Up So That the System Sends the Email When a User Signs Up
 
-There are several ways to do this, some people create Rails Observers to fire off emails, others do it inside of the User Model. However, in Rails 3, mailers are really just another way to render a view. Instead of rendering a view and sending out the HTTP protocol, they are just sending it out through the Email protocols instead. Due to this, it makes sense to just have your controller tell the mailer to send an email when a user is successfully created.
+There are several ways to do this, some people create Rails Observers to fire off emails, others do it inside of the User Model. However, mailers are really just another way to render a view. Instead of rendering a view and sending out the HTTP protocol, they are just sending it out through the Email protocols instead. Due to this, it makes sense to just have your controller tell the mailer to send an email when a user is successfully created.
 
 Setting this up is painfully simple.
 
@@ -145,10 +149,6 @@ This provides a much simpler implementation that does not require the registerin
 
 The method `welcome_email` returns a `Mail::Message` object which can then just be told `deliver` to send itself out.
 
-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. 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.
-
 ### Auto encoding header values
 
 Action Mailer now handles the auto encoding of multibyte characters inside of headers and bodies.

guides/source/action_view_overview.md

@@ -1263,10 +1263,8 @@ Creates a field set for grouping HTML form elements.
 
 Creates a file upload field.
 
-Prior to Rails 3.1, if you are using file uploads, then you will need to set the multipart option for the form tag. Rails 3.1+ does this automatically.
-
 ```html+erb
-<%= form_tag {action: "post"}, {multipart: true} do %>
+<%= form_tag {action: "post"} do %>
   <label for="file">File to Upload</label> <%= file_field_tag "file" %>
   <%= submit_tag %>
 <% end %>

guides/source/active_record_callbacks.md

@@ -4,11 +4,11 @@ Active Record Callbacks
 This guide teaches you how to hook into the life cycle of your Active Record
 objects.
 
-After reading this guide and trying out the presented concepts, we hope that you'll be able to:
+After reading this guide, you will know:
 
-* Understand the life cycle of Active Record objects
-* Create callback methods that respond to events in the object life cycle
-* Create special classes that encapsulate common behavior for your callbacks
+* The life cycle of Active Record objects.
+* How to create callback methods that respond to events in the object life cycle.
+* How to create special classes that encapsulate common behavior for your callbacks.
 
 --------------------------------------------------------------------------------
 

guides/source/active_record_querying.md

@@ -5,13 +5,13 @@ This guide covers different ways to retrieve data from the database using Active
 
 After reading this guide, you will know:
 
-* Find records using a variety of methods and conditions.
-* Specify the order, retrieved attributes, grouping, and other properties of the found records.
-* Use eager loading to reduce the number of database queries needed for data retrieval.
-* Use dynamic finders methods.
-* Check for the existence of particular records.
-* Perform various calculations on Active Record models.
-* Run EXPLAIN on relations.
+* How to find records using a variety of methods and conditions.
+* How to specify the order, retrieved attributes, grouping, and other properties of the found records.
+* How to use eager loading to reduce the number of database queries needed for data retrieval.
+* How to use dynamic finders methods.
+* How to check for the existence of particular records.
+* How to perform various calculations on Active Record models.
+* How to run EXPLAIN on relations.
 
 --------------------------------------------------------------------------------
 
@@ -1204,7 +1204,7 @@ class Client < ActiveRecord::Base
 end
 ```
 
-### Removing all scoping
+### Removing All Scoping
 
 If we wish to remove scoping for any reason we can use the `unscoped` method. This is
 especially useful if a `default_scope` is specified in the model and should not be
@@ -1236,9 +1236,7 @@ You can specify an exclamation point (`!`) on the end of the dynamic finders to
 
 If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`.
 
-WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior will be changed in Rails 3.2 to throw an `ArgumentError`.
-
-Find or build a new object
+Find or Build a New Object
 --------------------------
 
 It's common that you need to find a record or create it if it doesn't exist. You can do that with the `find_or_create_by` and `find_or_create_by!` methods.

guides/source/active_record_validations.md

@@ -6,9 +6,9 @@ the database using Active Record's validations feature.
 
 After reading this guide, you will know:
 
-* Use the built-in Active Record validation helpers
-* Create your own custom validation methods
-* Work with the error messages generated by the validation process
+* How to use the built-in Active Record validation helpers.
+* How to create your own custom validation methods.
+* How to work with the error messages generated by the validation process.
 
 --------------------------------------------------------------------------------
 
@@ -779,7 +779,7 @@ class Account < ActiveRecord::Base
 end
 ```
 
-### Grouping conditional validations
+### Grouping Conditional validations
 
 Sometimes it is useful to have multiple validations use one condition, it can
 be easily achieved using `with_options`.
@@ -796,7 +796,7 @@ end
 All validations inside of `with_options` block will have automatically passed
 the condition `if: :is_admin?`
 
-### Combining validation conditions
+### Combining Validation Conditions
 
 On the other hand, when multiple conditions define whether or not a validation
 should happen, an `Array` can be used. Moreover, you can apply both `:if` and

guides/source/active_support_core_extensions.md

@@ -7,6 +7,11 @@ It offers a richer bottom-line at the language level, targeted both at the devel
 
 After reading this guide, you will know:
 
+* What Core Extensions are.
+* How to load all extensions.
+* How to cherry-pick just the extensions you want.
+* What extensions ActiveSupport provides.
+
 --------------------------------------------------------------------------------
 
 How to Load Core Extensions
@@ -1120,8 +1125,6 @@ C.subclasses # => [B, D]
 
 The order in which these classes are returned is unspecified.
 
-WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
-
 NOTE: Defined in `active_support/core_ext/class/subclasses.rb`.
 
 #### `descendants`
@@ -1157,7 +1160,7 @@ Inserting data into HTML templates needs extra care. For example, you can't just
 
 #### Safe Strings
 
-Active Support has the concept of <i>(html) safe</i> strings since Rails 3. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
+Active Support has the concept of <i>(html) safe</i> strings. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
 
 Strings are considered to be <i>unsafe</i> by default:
 
@@ -1194,10 +1197,10 @@ Safe arguments are directly appended:
 "".html_safe + "<".html_safe # => "<"
 ```
 
-These methods should not be used in ordinary views. In Rails 3 unsafe values are automatically escaped:
+These methods should not be used in ordinary views. Unsafe values are automatically escaped:
 
 ```erb
-<%= @review.title %> <%# fine in Rails 3, escaped if needed %>
+<%= @review.title %> <%# fine, escaped if needed %>
 ```
 
 To insert something verbatim use the `raw` helper rather than calling `html_safe`:

guides/source/api_documentation_guidelines.md

@@ -5,6 +5,9 @@ This guide documents the Ruby on Rails API documentation guidelines.
 
 After reading this guide, you will know:
 
+* How to write effective prose for documentation purposes.
+* Style guidelines for documenting different kinds of Ruby code.
+
 --------------------------------------------------------------------------------
 
 RDoc