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

Conflicts:
	railties/guides/source/ajax_on_rails.textile
	railties/guides/source/generators.textile

4 files changed, 112 insertions, 25 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb
index ab1fa7cd5b..9eba4642b8 100644
--- a/activesupport/lib/active_support/core_ext/array/random_access.rb
+++ b/activesupport/lib/active_support/core_ext/array/random_access.rb
@@ -1,12 +1,15 @@
 class Array
   # Backport of Array#sample based on Marc-Andre Lafortune's https://github.com/marcandre/backports/
   # Returns a random element or +n+ random elements from the array.
-  # If the array is empty and +n+ is nil, returns <tt>nil</tt>. if +n+ is passed, returns <tt>[]</tt>.
+  # If the array is empty and +n+ is nil, returns <tt>nil</tt>.
+  # If +n+ is passed and its value is less than 0, it raises an +ArgumentError+ exception.
+  # If the value of +n+ is equal or greater than 0 it returns <tt>[]</tt>.
   #
-  #   [1,2,3,4,5,6].sample    # => 4
-  #   [1,2,3,4,5,6].sample(3) # => [2, 4, 5]
-  #              [].sample    # => nil
-  #              [].sample(3) # => []
+  #   [1,2,3,4,5,6].sample     # => 4
+  #   [1,2,3,4,5,6].sample(3)  # => [2, 4, 5]
+  #   [1,2,3,4,5,6].sample(-3) # => ArgumentError: negative sample number
+  #              [].sample     # => nil
+  #              [].sample(3)  # => []
   def sample(n=nil)
     return self[Kernel.rand(size)] if n.nil?
     n = n.to_int
diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb
index d0c1ea8326..20085c4fb3 100644
--- a/activesupport/lib/active_support/core_ext/object/blank.rb
+++ b/activesupport/lib/active_support/core_ext/object/blank.rb
@@ -18,8 +18,8 @@ class Object
     !blank?
   end
 
-  # Returns object if it's #present? otherwise returns nil.
-  # object.presence is equivalent to object.present? ? object : nil.
+  # Returns object if it's <tt>present?</tt> otherwise returns +nil+.
+  # <tt>object.presence</tt> is equivalent to <tt>object.present? ? object : nil</tt>.
   #
   # This is handy for any representation of objects where blank is the same
   # as not present at all.  For example, this simplifies a common check for
@@ -37,39 +37,72 @@ class Object
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # +nil+ is blank:
+  #
+  #   nil.blank? # => true
+  #
   def blank?
     true
   end
 end
 
-class FalseClass #:nodoc:
+class FalseClass
+  # +false+ is blank:
+  #
+  #   false.blank? # => true
+  #
   def blank?
     true
   end
 end
 
-class TrueClass #:nodoc:
+class TrueClass
+  # +true+ is not blank:
+  #
+  #   true.blank? # => false
+  #
   def blank?
     false
   end
 end
 
-class Array #:nodoc:
+class Array
+  # An array is blank if it's empty:
+  #
+  #   [].blank?      # => true
+  #   [1,2,3].blank? # => false
+  #
   alias_method :blank?, :empty?
 end
 
-class Hash #:nodoc:
+class Hash
+  # A hash is blank if it's empty:
+  #
+  #   {}.blank?                # => true
+  #   {:key => 'value'}.blank? # => false
+  #
   alias_method :blank?, :empty?
 end
 
-class String #:nodoc:
+class String
+  # A string is blank if it's empty or contains whitespaces only:
+  #
+  #   "".blank?                 # => true
+  #   "   ".blank?              # => true
+  #   " something here ".blank? # => false
+  #
   def blank?
     self !~ /\S/
   end
 end
 
 class Numeric #:nodoc:
+  # No number is blank:
+  #
+  #   1.blank? # => false
+  #   0.blank? # => false
+  #
   def blank?
     false
   end
diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb
index b05325790c..02cb5dfee7 100644
--- a/activesupport/lib/active_support/core_ext/object/duplicable.rb
+++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb
@@ -15,50 +15,89 @@
 # That's why we hardcode the following cases and check duplicable? instead of
 # using that rescue idiom.
 class Object
-  # Can you safely .dup this object?
-  # False for nil, false, true, symbols, numbers, class and module objects; true otherwise.
+  # Can you safely dup this object?
+  #
+  # False for +nil+, +false+, +true+, symbols, numbers, class and module objects;
+  # true otherwise.
   def duplicable?
     true
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # +nil+ is not duplicable:
+  #
+  #   nil.duplicable? # => false
+  #   nil.dup         # => TypeError: can't dup NilClass
+  #
   def duplicable?
     false
   end
 end
 
-class FalseClass #:nodoc:
+class FalseClass
+  # +false+ is not duplicable:
+  #
+  #   false.duplicable? # => false
+  #   false.dup         # => TypeError: can't dup FalseClass
+  #
   def duplicable?
     false
   end
 end
 
-class TrueClass #:nodoc:
+class TrueClass
+  # +true+ is not duplicable:
+  #
+  #   true.duplicable? # => false
+  #   true.dup         # => TypeError: can't dup TrueClass
+  #
   def duplicable?
     false
   end
 end
 
-class Symbol #:nodoc:
+class Symbol
+  # Symbols are not duplicable:
+  #
+  #   :my_symbol.duplicable? # => false
+  #   :my_symbol.dup         # => TypeError: can't dup Symbol
+  #
   def duplicable?
     false
   end
 end
 
-class Numeric #:nodoc:
+class Numeric
+  # Numbers are not duplicable:
+  #
+  #  3.duplicable? # => false
+  #  3.dup         # => TypeError: can't dup Fixnum
+  #
   def duplicable?
     false
   end
 end
 
-class Class #:nodoc:
+class Class
+  # Classes are not duplicable:
+  #
+  #  c = Class.new # => #<Class:0x10328fd80>
+  #  c.dup         # => #<Class:0x10328fd80>
+  #
+  # Note +dup+ returned the same class object.
   def duplicable?
     false
   end
 end
 
-class Module #:nodoc:
+class Module
+  # Modules are not duplicable:
+  #
+  #  m = Module.new # => #<Module:0x10328b6e0>
+  #  m.dup          # => #<Module:0x10328b6e0>
+  #
+  # Note +dup+ returned the same module object.
   def duplicable?
     false
   end
diff --git a/activesupport/lib/active_support/core_ext/object/try.rb b/activesupport/lib/active_support/core_ext/object/try.rb
index 04619124a1..aedf5c8c82 100644
--- a/activesupport/lib/active_support/core_ext/object/try.rb
+++ b/activesupport/lib/active_support/core_ext/object/try.rb
@@ -9,12 +9,12 @@ class Object
   #
   # ==== Examples
   #
-  # Without try
+  # Without +try+
   #   @person && @person.name
   # or
   #   @person ? @person.name : nil
   #
-  # With try
+  # With +try+
   #   @person.try(:name)
   #
   # +try+ also accepts arguments and/or a block, for the method it is trying
@@ -34,7 +34,19 @@ class Object
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # Instances of +NilClass+ return always +nil+.
+  # It becomes specially helpful when navigating through associations that may return +nil+.
+  #
+  # === Examples
+  #
+  #   nil.try(:name) # => nil
+  #
+  # Without +try+
+  #   @person && !@person.children.blank? && @person.children.first.name
+  #
+  # With +try+
+  #   @person.try(:children).try(:first).try(:name)
   def try(*args)
     nil
   end