Merge docrails

4 files changed, 61 insertions, 27 deletions

diff --git a/activesupport/lib/active_support/base64.rb b/activesupport/lib/active_support/base64.rb
index 602eef06b2..acb8e5a967 100644
--- a/activesupport/lib/active_support/base64.rb
+++ b/activesupport/lib/active_support/base64.rb
@@ -7,13 +7,24 @@ module ActiveSupport
   if defined? ::Base64
     Base64 = ::Base64
   else
-    # Ruby 1.9 doesn't provide base64, so we wrap this here
+    # Base64 provides utility methods for encoding and de-coding binary data 
+    # using a base 64 representation. A base 64 representation of binary data
+    # consists entirely of printable US-ASCII characters. The Base64 module
+    # is included in Ruby 1.8, but has been removed in Ruby 1.9.
     module Base64
-
+      # Encodes a string to its base 64 representation. Each 60 characters of
+      # output is separated by a newline character.
+      #
+      #  ActiveSupport::Base64.encode64("Original unencoded string") 
+      #  # => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==\n"
       def self.encode64(data)
         [data].pack("m")
       end
 
+      # Decodes a base 64 encoded string to its original representation.
+      #
+      #  ActiveSupport::Base64.decode64("T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==") 
+      #  # => "Original unencoded string"
       def self.decode64(data)
         data.unpack("m").first
       end
diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index 779ca40aea..a3b2a54c7d 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -23,47 +23,47 @@ module ActiveSupport #:nodoc:
           self[0..position]
         end
 
-        # Equals to <tt>self[1]</tt>.
+        # Equal to <tt>self[1]</tt>.
         def second
           self[1]
         end
 
-        # Equals to <tt>self[2]</tt>.
+        # Equal to <tt>self[2]</tt>.
         def third
           self[2]
         end
 
-        # Equals to <tt>self[3]</tt>.
+        # Equal to <tt>self[3]</tt>.
         def fourth
           self[3]
         end
 
-        # Equals to <tt>self[4]</tt>.
+        # Equal to <tt>self[4]</tt>.
         def fifth
           self[4]
         end
 
-        # Equals to <tt>self[5]</tt>.
+        # Equal to <tt>self[5]</tt>.
         def sixth
           self[5]
         end
 
-        # Equals to <tt>self[6]</tt>.
+        # Equal to <tt>self[6]</tt>.
         def seventh
           self[6]
         end
 
-        # Equals to <tt>self[7]</tt>.
+        # Equal to <tt>self[7]</tt>.
         def eighth
           self[7]
         end
 
-        # Equals to <tt>self[8]</tt>.
+        # Equal to <tt>self[8]</tt>.
         def ninth
           self[8]
         end
 
-        # Equals to <tt>self[9]</tt>.
+        # Equal to <tt>self[9]</tt>.
         def tenth
           self[9]
         end
diff --git a/activesupport/lib/active_support/core_ext/base64/encoding.rb b/activesupport/lib/active_support/core_ext/base64/encoding.rb
index 1a40da8785..a9656c138e 100644
--- a/activesupport/lib/active_support/core_ext/base64/encoding.rb
+++ b/activesupport/lib/active_support/core_ext/base64/encoding.rb
@@ -4,6 +4,9 @@ module ActiveSupport #:nodoc:
       module Encoding
         # Encodes the value as base64 without the newline breaks. This makes the base64 encoding readily usable as URL parameters 
         # or memcache keys without further processing.
+        #
+        #  ActiveSupport::Base64.encode64s("Original unencoded string") 
+        #  # => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw=="
         def encode64s(value)
           encode64(value).gsub(/\n/, '')
         end
diff --git a/activesupport/lib/active_support/core_ext/object/misc.rb b/activesupport/lib/active_support/core_ext/object/misc.rb
index 06a7d05702..cd0a04d32a 100644
--- a/activesupport/lib/active_support/core_ext/object/misc.rb
+++ b/activesupport/lib/active_support/core_ext/object/misc.rb
@@ -1,30 +1,50 @@
 class Object
-  # A Ruby-ized realization of the K combinator, courtesy of Mikael Brockman.
+  # Returns +value+ after yielding +value+ to the block. This simplifies the
+  # process of constructing an object, performing work on the object, and then
+  # returning the object from a method. It is a Ruby-ized realization of the K
+  # combinator, courtesy of Mikael Brockman.
   #
-  #   def foo
-  #     returning values = [] do
-  #       values << 'bar'
-  #       values << 'baz'
-  #     end
-  #   end
+  # ==== Examples
   #
-  #   foo # => ['bar', 'baz']
+  #  # Without returning
+  #  def foo
+  #    values = []
+  #    values << "bar"
+  #    values << "baz"
+  #    return values
+  #  end
   #
-  #   def foo
-  #     returning [] do |values|
-  #       values << 'bar'
-  #       values << 'baz'
-  #     end
-  #   end
+  #  foo # => ['bar', 'baz']
   #
-  #   foo # => ['bar', 'baz']
+  #  # returning with a local variable
+  #  def foo
+  #    returning values = [] do
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
   #
+  #  foo # => ['bar', 'baz']
+  #  
+  #  # returning with a block argument
+  #  def foo
+  #    returning [] do |values|
+  #      values << 'bar'
+  #      values << 'baz'
+  #    end
+  #  end
+  #  
+  #  foo # => ['bar', 'baz']
   def returning(value)
     yield(value)
     value
   end
 
-  # An elegant way to refactor out common options
+  # An elegant way to factor duplication out of options passed to a series of
+  # method calls. Each method called in the block, with the block variable as
+  # the receiver, will have its options merged with the default +options+ hash
+  # provided. Each method called on the block variable must take an options
+  # hash as its final argument.
   # 
   #   with_options :order => 'created_at', :class_name => 'Comment' do |post|
   #     post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all