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

6 files changed, 105 insertions, 28 deletions

diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index 44d90ef732..a8f9dddae5 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -1,40 +1,48 @@
 class Array
   # Returns the tail of the array from +position+.
   #
-  #   %w( a b c d ).from(0)  # => %w( a b c d )
-  #   %w( a b c d ).from(2)  # => %w( c d )
-  #   %w( a b c d ).from(10) # => %w()
-  #   %w().from(0)           # => %w()
+  #   %w( a b c d ).from(0)  # => ["a", "b", "c", "d"]
+  #   %w( a b c d ).from(2)  # => ["c", "d"]
+  #   %w( a b c d ).from(10) # => []
+  #   %w().from(0)           # => []
   def from(position)
     self[position, length] || []
   end
 
   # Returns the beginning of the array up to +position+.
   #
-  #   %w( a b c d ).to(0)  # => %w( a )
-  #   %w( a b c d ).to(2)  # => %w( a b c )
-  #   %w( a b c d ).to(10) # => %w( a b c d )
-  #   %w().to(0)           # => %w()
+  #   %w( a b c d ).to(0)  # => ["a"]
+  #   %w( a b c d ).to(2)  # => ["a", "b", "c"]
+  #   %w( a b c d ).to(10) # => ["a", "b", "c", "d"]
+  #   %w().to(0)           # => []
   def to(position)
     first position + 1
   end
 
   # Equal to <tt>self[1]</tt>.
+  #
+  #   %w( a b c d e).second # => "b"
   def second
     self[1]
   end
 
   # Equal to <tt>self[2]</tt>.
+  #
+  #   %w( a b c d e).third # => "c"
   def third
     self[2]
   end
 
   # Equal to <tt>self[3]</tt>.
+  #
+  #   %w( a b c d e).fourth # => "d"
   def fourth
     self[3]
   end
 
   # Equal to <tt>self[4]</tt>.
+  #
+  #   %w( a b c d e).fifth # => "e"
   def fifth
     self[4]
   end
diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb
index 24aa28b895..1e0de651c7 100644
--- a/activesupport/lib/active_support/core_ext/array/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/array/conversions.rb
@@ -4,10 +4,55 @@ require 'active_support/core_ext/hash/reverse_merge'
 require 'active_support/core_ext/string/inflections'
 
 class Array
-  # Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:
-  # * <tt>:words_connector</tt> - The sign or word used to join the elements in arrays with two or more elements (default: ", ")
-  # * <tt>:two_words_connector</tt> - The sign or word used to join the elements in arrays with two elements (default: " and ")
-  # * <tt>:last_word_connector</tt> - The sign or word used to join the last element in arrays with three or more elements (default: ", and ")
+  # Converts the array to a comma-separated sentence where the last element is
+  # joined by the connector word.
+  #
+  # You can pass the following options to change the default behaviour. If you
+  # pass an option key that doesn't exist in the list below, it will raise an
+  # <tt>ArgumentError</tt>.
+  #
+  # Options:
+  #
+  # * <tt>:words_connector</tt> - The sign or word used to join the elements
+  #   in arrays with two or more elements (default: ", ").
+  # * <tt>:two_words_connector</tt> - The sign or word used to join the elements
+  #   in arrays with two elements (default: " and ").
+  # * <tt>:last_word_connector</tt> - The sign or word used to join the last element
+  #   in arrays with three or more elements (default: ", and ").
+  # * <tt>:locale</tt> - If +i18n+ is available, you can set a locale and use
+  #   the connector options defined on the 'support.array' namespace in the
+  #   corresponding dictionary file.
+  #
+  #   [].to_sentence                      # => ""
+  #   ['one'].to_sentence                 # => "one"
+  #   ['one', 'two'].to_sentence          # => "one and two"
+  #   ['one', 'two', 'three'].to_sentence # => "one, two, and three"
+  #
+  #   ['one', 'two'].to_sentence(passing: 'invalid option')
+  #   # => ArgumentError: Unknown key :passing
+  #
+  #   ['one', 'two'].to_sentence(two_words_connector: '-')
+  #   # => "one-two"
+  #
+  #   ['one', 'two', 'three'].to_sentence(words_connector: ' or ', last_word_connector: ' or at least ')
+  #   # => "one or two or at least three"
+  #
+  # Examples using <tt>:locale</tt> option:
+  #
+  #   # Given this locale dictionary:
+  #   # 
+  #   #   es:
+  #   #     support:
+  #   #       array:
+  #   #         words_connector: " o "
+  #   #         two_words_connector: " y "
+  #   #         last_word_connector: " o al menos "
+  #
+  #   ['uno', 'dos'].to_sentence(locale: :es)
+  #   # => "uno y dos"
+  #
+  #   ['uno', 'dos', 'tres'].to_sentence(locale: :es)
+  #   # => "uno o dos o al menos tres"
   def to_sentence(options = {})
     options.assert_valid_keys(:words_connector, :two_words_connector, :last_word_connector, :locale)
 
@@ -39,7 +84,17 @@ class Array
   end
 
   # Converts a collection of elements into a formatted string by calling
-  # <tt>to_s</tt> on all elements and joining them:
+  # <tt>to_s</tt> on all elements and joining them. Having this model:
+  #
+  #   class Blog < ActiveRecord::Base
+  #     def to_s
+  #       title
+  #     end
+  #   end
+  #
+  #   Blog.all.map(&:title) #=> ["First Post", "Second Post", "Third post"]
+  #
+  # <tt>to_formatted_s</tt> shows us:
   #
   #   Blog.all.to_formatted_s # => "First PostSecond PostThird Post"
   #
diff --git a/activesupport/lib/active_support/core_ext/class/subclasses.rb b/activesupport/lib/active_support/core_ext/class/subclasses.rb
index 74ea047c24..c2e0ebb3d4 100644
--- a/activesupport/lib/active_support/core_ext/class/subclasses.rb
+++ b/activesupport/lib/active_support/core_ext/class/subclasses.rb
@@ -1,11 +1,11 @@
 require 'active_support/core_ext/module/anonymous'
 require 'active_support/core_ext/module/reachable'
 
-class Class #:nodoc:
+class Class
   begin
     ObjectSpace.each_object(Class.new) {}
 
-    def descendants
+    def descendants # :nodoc:
       descendants = []
       ObjectSpace.each_object(singleton_class) do |k|
         descendants.unshift k unless k == self
@@ -13,7 +13,7 @@ class Class #:nodoc:
       descendants
     end
   rescue StandardError # JRuby
-    def descendants
+    def descendants # :nodoc:
       descendants = []
       ObjectSpace.each_object(Class) do |k|
         descendants.unshift k if k < self
@@ -25,7 +25,13 @@ class Class #:nodoc:
 
   # Returns an array with the direct children of +self+.
   #
-  #   Integer.subclasses # => [Bignum, Fixnum]
+  #   Integer.subclasses # => [Fixnum, Bignum]
+  #
+  #   class Foo; end
+  #   class Bar < Foo; end
+  #   class Baz < Foo; end
+  #
+  #   Foo.subclasses # => [Baz, Bar]
   def subclasses
     subclasses, chain = [], descendants
     chain.each do |k|
diff --git a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
index b8cb2e347f..672cc0256f 100644
--- a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
+++ b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb
@@ -46,19 +46,19 @@ class Module
   # Extends the module object with module and instance accessors for class attributes,
   # just like the native attr* accessors for instance attributes.
   #
-  #  module AppConfiguration
-  #    mattr_accessor :google_api_key
+  #   module AppConfiguration
+  #     mattr_accessor :google_api_key
   #
-  #    self.google_api_key = "123456789"
-  #  end
+  #     self.google_api_key = "123456789"
+  #   end
   #
-  #  AppConfiguration.google_api_key # => "123456789"
-  #  AppConfiguration.google_api_key = "overriding the api key!"
-  #  AppConfiguration.google_api_key # => "overriding the api key!"
+  #   AppConfiguration.google_api_key # => "123456789"
+  #   AppConfiguration.google_api_key = "overriding the api key!"
+  #   AppConfiguration.google_api_key # => "overriding the api key!"
   #
-  # To opt out of the instance writer method, pass instance_writer: false.
-  # To opt out of the instance reader method, pass instance_reader: false.
-  # To opt out of both instance methods, pass instance_accessor: false.
+  # To opt out of the instance writer method, pass <tt>instance_writer: false</tt>.
+  # To opt out of the instance reader method, pass <tt>instance_reader: false</tt>.
+  # To opt out of both instance methods, pass <tt>instance_accessor: false</tt>.
   def mattr_accessor(*syms)
     mattr_reader(*syms)
     mattr_writer(*syms)
diff --git a/activesupport/lib/active_support/json/decoding.rb b/activesupport/lib/active_support/json/decoding.rb
index 986a764479..72fd97ceee 100644
--- a/activesupport/lib/active_support/json/decoding.rb
+++ b/activesupport/lib/active_support/json/decoding.rb
@@ -8,6 +8,11 @@ module ActiveSupport
 
   module JSON
     class << self
+      # Parses a JSON string (JavaScript Object Notation) into a hash.
+      # See www.json.org for more info.
+      #
+      #   ActiveSupport::JSON.decode("{\"team\":\"rails\",\"players\":\"36\"}")
+      #   => {"team" => "rails", "players" => "36"}
       def decode(json, options ={})
         data = MultiJson.load(json, options)
         if ActiveSupport.parse_json_times
diff --git a/activesupport/lib/active_support/json/encoding.rb b/activesupport/lib/active_support/json/encoding.rb
index 41fe61e790..ded02c873a 100644
--- a/activesupport/lib/active_support/json/encoding.rb
+++ b/activesupport/lib/active_support/json/encoding.rb
@@ -25,7 +25,10 @@ module ActiveSupport
     # matches YAML-formatted dates
     DATE_REGEX = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[T \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?(([ \t]*)Z|[-+]\d{2}?(:\d{2})?))$/
 
-    # Dumps object in JSON (JavaScript Object Notation). See www.json.org for more info.
+    # Dumps objects in JSON (JavaScript Object Notation). See www.json.org for more info.
+    #
+    #   ActiveSupport::JSON.encode({team: 'rails', players: '36'})
+    #   # => "{\"team\":\"rails\",\"players\":\"36\"}"
     def self.encode(value, options = nil)
       Encoding::Encoder.new(options).encode(value)
     end