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

Conflicts:
	activesupport/lib/active_support/core_ext/hash/slice.rb
	guides/source/active_support_core_extensions.md

Author: vijaydev

actionpack/lib/action_controller/metal/strong_parameters.rb

@@ -19,13 +19,13 @@ def initialize(param) # :nodoc:
     end
   end
 
-  # == Action Controller Parameters
+  # == Action Controller \Parameters
   #
   # Allows to choose which attributes should be whitelisted for mass updating
   # and thus prevent accidentally exposing that which shouldn’t be exposed.
   # Provides two methods for this purpose: #require and #permit. The former is
   # used to mark parameters as required. The latter is used to set the parameter
-  # as permitted and limit which attributes should be allowed for mass updating.
+  # as permitted and limit which attributes should be allowed for mass updating.
   #
   #   params = ActionController::Parameters.new({
   #     person: {
@@ -77,12 +77,12 @@ class Parameters < ActiveSupport::HashWithIndifferentAccess
     #
     #   params = ActionController::Parameters.new(name: 'Francesco')
     #   params.permitted?  # => false
-    #   Person.new(params) # => ActiveModel::ForbiddenAttributesError
+    #   Person.new(params) # => ActiveModel::ForbiddenAttributesError
     #
     #   ActionController::Parameters.permit_all_parameters = true
     #
     #   params = ActionController::Parameters.new(name: 'Francesco')
-    #   params.permitted?  # => true
+    #   params.permitted?  # => true
     #   Person.new(params) # => #<Person id: nil, name: "Francesco">
     def initialize(attributes = nil)
       super(attributes)
@@ -106,7 +106,7 @@ def permitted?
     #   end
     #
     #   params = ActionController::Parameters.new(name: 'Francesco')
-    #   params.permitted?  # => false
+    #   params.permitted?  # => false
     #   Person.new(params) # => ActiveModel::ForbiddenAttributesError
     #   params.permit!
     #   params.permitted?  # => true
@@ -125,7 +125,7 @@ def permit!
     # the parameter at the given +key+, otherwise raises an
     # <tt>ActionController::ParameterMissing</tt> error.
     #
-    #   ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person)
+    #   ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person)
     #   # => {"name"=>"Francesco"}
     #
     #   ActionController::Parameters.new(person: nil).require(:person)
@@ -141,21 +141,21 @@ def require(key)
     alias :required :require
 
     # Returns a new <tt>ActionController::Parameters</tt> instance that
-    # includes only the given +filters+ and sets the +permitted+ for the
-    # object to +true+. This is useful for limiting which attributes
+    # includes only the given +filters+ and sets the +permitted+ attribute
+    # for the object to +true+. This is useful for limiting which attributes
     # should be allowed for mass updating.
     #
     #   params = ActionController::Parameters.new(user: { name: 'Francesco', age: 22, role: 'admin' })
     #   permitted = params.require(:user).permit(:name, :age)
-    #   permitted.permitted?      # => true
+    #   permitted.permitted?      # => true
     #   permitted.has_key?(:name) # => true
     #   permitted.has_key?(:age)  # => true
     #   permitted.has_key?(:role) # => false
     #
     # You can also use +permit+ on nested parameters, like:
     #
     #   params = ActionController::Parameters.new({
-    #     person: {
+    #     person: {
     #       name: 'Francesco',
     #       age:  22,
     #       pets: [{
@@ -168,7 +168,7 @@ def require(key)
     #   permitted = params.permit(person: [ :name, { pets: :name } ])
     #   permitted.permitted?                    # => true
     #   permitted[:person][:name]               # => "Francesco"
-    #   permitted[:person][:age]                # => nil
+    #   permitted[:person][:age]                # => nil
     #   permitted[:person][:pets][0][:name]     # => "Purplish"
     #   permitted[:person][:pets][0][:category] # => nil
     #
@@ -229,7 +229,7 @@ def permit(*filters)
     # returns +nil+.
     #
     #   params = ActionController::Parameters.new(person: { name: 'Francesco' })
-    #   params[:person] # => {"name"=>"Francesco"}
+    #   params[:person] # => {"name"=>"Francesco"}
     #   params[:none]   # => nil
     def [](key)
       convert_hashes_to_parameters(key, super)
@@ -242,10 +242,10 @@ def [](key)
     # is given, then that will be run and its result returned.
     #
     #   params = ActionController::Parameters.new(person: { name: 'Francesco' })
-    #   params.fetch(:person)         # => {"name"=>"Francesco"}
-    #   params.fetch(:none)           # => ActionController::ParameterMissing: param not found: none
+    #   params.fetch(:person)               # => {"name"=>"Francesco"}
+    #   params.fetch(:none)                 # => ActionController::ParameterMissing: param not found: none
     #   params.fetch(:none, 'Francesco')    # => "Francesco"
-    #   params.fetch(:none) { 'Francesco' } # => "Francesco"
+    #   params.fetch(:none) { 'Francesco' } # => "Francesco"
     def fetch(key, *args)
       convert_hashes_to_parameters(key, super)
     rescue KeyError
@@ -303,7 +303,7 @@ def each_element(object)
   # == Strong \Parameters
   #
   # It provides an interface for protecting attributes from end-user
-  # assignment. This makes Action Controller parameters forbidden
+  # assignment. This makes Action Controller parameters forbidden
   # to be used in Active Model mass assignment until they have been
   # whitelisted.
   #
@@ -332,14 +332,39 @@ def each_element(object)
   #
   #     private
   #       # Using a private method to encapsulate the permissible parameters is
-  #       # just a good pattern since you'll be able to reuse the same permit
+  #       # just a good pattern since you'll be able to reuse the same permit
   #       # list between create and update. Also, you can specialize this method
   #       # with per-user checking of permissible attributes.
   #       def person_params
   #         params.require(:person).permit(:name, :age)
   #       end
   #   end
   #
+  # In order to use <tt>accepts_nested_attribute_for</tt> with Strong \Parameters, you
+  # will need to specify which nested attributes should be whitelisted.
+  #
+  #   class Person
+  #     has_many :pets
+  #     accepts_nested_attributes_for :pets
+  #   end
+  #
+  #   class PeopleController < ActionController::Base
+  #     def create
+  #       Person.create(person_params)
+  #     end
+  #
+  #     ...
+  #
+  #     private
+  #
+  #       def person_params
+  #         # It's mandatory to specify the nested attributes that should be whitelisted.
+  #         # If you use `permit` with just the key that points to the nested attributes hash,
+  #         # it will return an empty hash.
+  #         params.require(:person).permit(:name, :age, pets_attributes: { :name, :category })
+  #       end
+  #   end
+  #
   # See ActionController::Parameters.require and ActionController::Parameters.permit
   # for more information.
   module StrongParameters

activemodel/README.rdoc

@@ -75,7 +75,11 @@ behavior out of the box:
 
 * Tracking value changes
 
-  The ActiveModel::Dirty module allows for tracking attribute changes:
+    class Person
+      include ActiveModel::Dirty
+
+      attr_accessor :name
+    end
 
     person = Person.new
     person.name # => nil
@@ -152,9 +156,31 @@ behavior out of the box:
   ActiveModel::Serialization provides a standard interface for your object
   to provide +to_json+ or +to_xml+ serialization.
 
+    class SerialPerson
+      include ActiveModel::Serialization
+
+      attr_accessor :name
+
+      def attributes
+        {'name' => name}
+      end
+    end
+
     s = SerialPerson.new
     s.serializable_hash   # => {"name"=>nil}
+
+    class SerialPerson
+      include ActiveModel::Serializers::JSON
+    end
+
+    s = SerialPerson.new
     s.to_json             # => "{\"name\":null}"
+
+    class SerialPerson
+      include ActiveModel::Serializers::Xml
+    end
+
+    s = SerialPerson.new
     s.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
 
   {Learn more}[link:classes/ActiveModel/Serialization.html]

activemodel/lib/active_model/attribute_methods.rb

@@ -11,7 +11,7 @@ module ActiveModel
   #   # => ActiveModel::MissingAttributeError: missing attribute: user_id
   class MissingAttributeError < NoMethodError
   end
-  # == Active Model Attribute Methods
+  # == Active \Model Attribute Methods
   #
   # <tt>ActiveModel::AttributeMethods</tt> provides a way to add prefixes and
   # suffixes to your methods as well as handling the creation of Active Record

activemodel/lib/active_model/callbacks.rb

@@ -1,7 +1,7 @@
 require 'active_support/callbacks'
 
 module ActiveModel
-  # == Active Model Callbacks
+  # == Active \Model \Callbacks
   #
   # Provides an interface for any class to have Active Record like callbacks.
   #

activemodel/lib/active_model/conversion.rb

@@ -1,7 +1,7 @@
 require 'active_support/inflector'
 
 module ActiveModel
-  # == Active Model Conversions
+  # == Active \Model Conversions
   #
   # Handles default conversions: to_model, to_key, to_param, and to_partial_path.
   #

activemodel/lib/active_model/dirty.rb

@@ -3,7 +3,7 @@
 require 'active_support/core_ext/object/duplicable'
 
 module ActiveModel
-  # == Active Model Dirty
+  # == Active \Model \Dirty
   #
   # Provides a way to track changes in your object in the same way as
   # Active Record does.

activemodel/lib/active_model/errors.rb

@@ -4,7 +4,7 @@
 require 'active_support/core_ext/string/inflections'
 
 module ActiveModel
-  # == Active Model Errors
+  # == Active \Model \Errors
   #
   # Provides a modified +Hash+ that you can include in your object
   # for handling error messages and interacting with Action Pack helpers.

activemodel/lib/active_model/lint.rb

@@ -1,8 +1,8 @@
 module ActiveModel
   module Lint
-    # == Active Model Lint Tests
+    # == Active \Model \Lint \Tests
     #
-    # You can test whether an object is compliant with the Active Model API by
+    # You can test whether an object is compliant with the Active \Model API by
     # including <tt>ActiveModel::Lint::Tests</tt> in your TestCase. It will
     # include tests that tell you whether your object is fully compliant,
     # or if not, which aspects of the API are not implemented.
@@ -71,7 +71,7 @@ def test_persisted?
         assert_boolean model.persisted?, "persisted?"
       end
 
-      # == Naming
+      # == \Naming
       #
       # Model.model_name must return a string with some convenience methods:
       # <tt>:human</tt>, <tt>:singular</tt> and <tt>:plural</tt>. Check
@@ -85,7 +85,7 @@ def test_model_naming
         assert model_name.plural.respond_to?(:to_str)
       end
 
-      # == Errors Testing
+      # == \Errors Testing
       #
       # Returns an object that implements [](attribute) defined which returns an
       # Array of Strings that are the errors for the attribute in question.

activemodel/lib/active_model/model.rb

@@ -1,6 +1,6 @@
 module ActiveModel
 
-  # == Active Model Basic Model
+  # == Active \Model Basic \Model
   #
   # Includes the required interface for an object to interact with
   # <tt>ActionPack</tt>, using different <tt>ActiveModel</tt> modules.

activemodel/lib/active_model/naming.rb

@@ -195,7 +195,7 @@ def _singularize(string, replacement='_')
     end
   end
 
-  # == Active Model Naming
+  # == Active \Model \Naming
   #
   # Creates a +model_name+ method on your object.
   #

activemodel/lib/active_model/observing.rb

@@ -8,7 +8,7 @@
 require 'active_support/descendants_tracker'
 
 module ActiveModel
-  # == Active Model Observers Activation
+  # == Active \Model Observers Activation
   module Observing
     extend ActiveSupport::Concern
 
@@ -229,7 +229,7 @@ def notify_observers(method, *extra_args)
     end
   end
 
-  # == Active Model Observers
+  # == Active \Model Observers
   #
   # Observer classes respond to life cycle callbacks to implement trigger-like
   # behavior outside the original class. This is a great way to reduce the
@@ -257,7 +257,7 @@ def notify_observers(method, *extra_args)
   #
   # This Observer uses logger to log when specific callbacks are triggered.
   #
-  # == Observing a class that can't be inferred
+  # == \Observing a class that can't be inferred
   #
   # Observers will by default be mapped to the class with which they share a
   # name. So <tt>CommentObserver</tt> will be tied to observing <tt>Comment</tt>,

activemodel/lib/active_model/railtie.rb

@@ -2,7 +2,7 @@
 require "rails"
 
 module ActiveModel
-  class Railtie < Rails::Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     config.eager_load_namespaces << ActiveModel
   end
-end
+end

activemodel/lib/active_model/secure_password.rb

@@ -44,7 +44,7 @@ def has_secure_password(options = {})
         if options.fetch(:validations, true)
           validates_confirmation_of :password
           validates_presence_of     :password, :on => :create
-          
+
           before_create { raise "Password digest missing on new record" if password_digest.blank? }
         end
 
@@ -68,7 +68,7 @@ module InstanceMethodsOnActivation
       #   user = User.new(name: 'david', password: 'mUc3m00RsqyRe')
       #   user.save
       #   user.authenticate('notright')      # => false
-      #   user.authenticate('mUc3m00RsqyRe') # => user
+      #   user.authenticate('mUc3m00RsqyRe') # => user
       def authenticate(unencrypted_password)
         BCrypt::Password.new(password_digest) == unencrypted_password && self
       end
@@ -84,7 +84,7 @@ def authenticate(unencrypted_password)
       #   user.password = nil
       #   user.password_digest # => nil
       #   user.password = 'mUc3m00RsqyRe'
-      #   user.password_digest # => "$2a$10$4LEA7r4YmNHtvlAvHhsYAeZmk/xeUVtMTYqwIvYY76EW5GUqDiP4."
+      #   user.password_digest # => "$2a$10$4LEA7r4YmNHtvlAvHhsYAeZmk/xeUVtMTYqwIvYY76EW5GUqDiP4."
       def password=(unencrypted_password)
         unless unencrypted_password.blank?
           @password = unencrypted_password

activemodel/lib/active_model/serialization.rb

@@ -2,7 +2,7 @@
 require 'active_support/core_ext/hash/slice'
 
 module ActiveModel
-  # == Active Model Serialization
+  # == Active \Model \Serialization
   #
   # Provides a basic serialization to a serializable_hash for your object.
   #

activemodel/lib/active_model/translation.rb

@@ -1,6 +1,6 @@
 module ActiveModel
 
-  # == Active Model Translation
+  # == Active \Model \Translation
   #
   # Provides integration between your object and the Rails internationalization
   # (i18n) framework.

activemodel/lib/active_model/validations.rb

@@ -7,7 +7,7 @@
 
 module ActiveModel
 
-  # == Active Model Validations
+  # == Active \Model Validations
   #
   # Provides a full validation framework to your objects.
   #

activemodel/lib/active_model/validations/acceptance.rb

@@ -1,6 +1,6 @@
 module ActiveModel
 
-  # == Active Model Acceptance Validator
+  # == Active \Model Acceptance \Validator
   module Validations
     class AcceptanceValidator < EachValidator #:nodoc:
       def initialize(options)