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

Conflicts:
	activesupport/lib/active_support/callbacks.rb

9 files changed, 93 insertions, 21 deletions

diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb
index 3c7dbb369c..c6c7e2821b 100644
--- a/activesupport/lib/active_support/callbacks.rb
+++ b/activesupport/lib/active_support/callbacks.rb
@@ -54,7 +54,6 @@ module ActiveSupport
   #   saving...
   #   - save
   #   saved
-  #
   module Callbacks
     extend Concern
 
@@ -73,7 +72,6 @@ module ActiveSupport
     #   run_callbacks :save do
     #     save
     #   end
-    #
     def run_callbacks(kind, &block)
       runner_name = self.class.__define_callbacks(kind, self)
       send(runner_name, &block)
@@ -198,7 +196,6 @@ module ActiveSupport
       #     yield self
       #   end
       # end
-      #
       def define_conditional_callback
         name = "_conditional_callback_#{@kind}_#{next_id}"
         @klass.class_eval <<-RUBY_EVAL,  __FILE__, __LINE__ + 1
@@ -252,7 +249,6 @@ module ActiveSupport
       #   Objects::
       #     a method is created that calls the before_foo method
       #     on the object.
-      #
       def _compile_filter(filter)
         method_name = "_callback_#{@kind}_#{next_id}"
         case filter
@@ -404,7 +400,6 @@ module ActiveSupport
       #   will be called only when it returns a false value.
       # * <tt>:prepend</tt> - If true, the callback will be prepended to the existing
       #   chain rather than appended.
-      #
       def set_callback(name, *filter_list, &block)
         mapped = nil
 
@@ -429,7 +424,6 @@ module ActiveSupport
       #   class Writer < Person
       #      skip_callback :validate, :before, :check_membership, :if => lambda { self.age > 18 }
       #   end
-      #
       def skip_callback(name, *filter_list, &block)
         __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options|
           filters.each do |filter|
@@ -448,7 +442,6 @@ module ActiveSupport
       end
 
       # Remove all set callbacks for the given event.
-      #
       def reset_callbacks(symbol)
         callbacks = send("_#{symbol}_callbacks")
 
@@ -529,7 +522,6 @@ module ActiveSupport
       #     define_callbacks :save, :scope => [:name]
       #
       #   would call <tt>Audit#save</tt>.
-      #
       def define_callbacks(*callbacks)
         config = callbacks.last.is_a?(Hash) ? callbacks.pop : {}
         callbacks.each do |callback|
diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb
index 4834eca8b1..9ea93d7226 100644
--- a/activesupport/lib/active_support/core_ext/array/wrap.rb
+++ b/activesupport/lib/active_support/core_ext/array/wrap.rb
@@ -25,9 +25,6 @@ class Array
   #   Array(:foo => :bar)      # => [[:foo, :bar]]
   #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
   #
-  #   Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
-  #   Array.wrap("foo\nbar")   # => ["foo\nbar"]
-  #
   # There's also a related idiom that uses the splat operator:
   #
   #   [*object]
diff --git a/activesupport/lib/active_support/core_ext/integer/multiple.rb b/activesupport/lib/active_support/core_ext/integer/multiple.rb
index 8dff217ddc..7c6c2f1ca7 100644
--- a/activesupport/lib/active_support/core_ext/integer/multiple.rb
+++ b/activesupport/lib/active_support/core_ext/integer/multiple.rb
@@ -1,5 +1,9 @@
 class Integer
   # Check whether the integer is evenly divisible by the argument.
+  #
+  #   0.multiple_of?(0)  #=> true
+  #   6.multiple_of?(5)  #=> false
+  #   10.multiple_of?(2) #=> true
   def multiple_of?(number)
     number != 0 ? self % number == 0 : zero?
   end
diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb
index 23aaee9c43..5c32a2453d 100644
--- a/activesupport/lib/active_support/core_ext/string/access.rb
+++ b/activesupport/lib/active_support/core_ext/string/access.rb
@@ -1,18 +1,79 @@
 require 'active_support/multibyte'
 
 class String
+  # If you pass a single Fixnum, returns a substring of one character at that
+  # position. The first character of the string is at position 0, the next at
+  # position 1, and so on. If a range is supplied, a substring containing
+  # characters at offsets given by the range is returned. In both cases, if an
+  # offset is negative, it is counted from the end of the string. Returns nil
+  # if the initial offset falls outside the string. Returns an empty string if
+  # the beginning of the range is greater than the end of the string.
+  #
+  #   str = "hello"
+  #   str.at(0)      #=> "h"
+  #   str.at(1..3)   #=> "ell"
+  #   str.at(-2)     #=> "l"
+  #   str.at(-2..-1) #=> "lo"
+  #   str.at(5)      #=> nil
+  #   str.at(5..-1)  #=> ""
+  #
+  # If a Regexp is given, the matching portion of the string is returned.
+  # If a String is given, that given string is returned if it occurs in
+  # the string. In both cases, nil is returned if there is no match.
+  #
+  #   str = "hello"
+  #   str.at(/lo/) #=> "lo"
+  #   str.at(/ol/) #=> nil
+  #   str.at("lo") #=> "lo"
+  #   str.at("ol") #=> nil
   def at(position)
     self[position]
   end
 
+  # Returns a substring from the given position to the end of the string.
+  # If the position is negative, it is counted from the end of the string.
+  #
+  #   str = "hello"
+  #   str.from(0)  #=> "hello"
+  #   str.from(3)  #=> "lo"
+  #   str.from(-2) #=> "lo"
+  #
+  # You can mix it with +to+ method and do fun things like:
+  #
+  #   str = "hello"
+  #   str.from(0).to(-1) #=> "hello"
+  #   str.from(1).to(-2) #=> "ell"
   def from(position)
     self[position..-1]
   end
 
+  # Returns a substring from the beginning of the string to the given position.
+  # If the position is negative, it is counted from the end of the string.
+  #
+  #   str = "hello"
+  #   str.to(0)  #=> "h"
+  #   str.to(3)  #=> "hell"
+  #   str.to(-2) #=> "hell"
+  #
+  # You can mix it with +from+ method and do fun things like:
+  #
+  #   str = "hello"
+  #   str.from(0).to(-1) #=> "hello"
+  #   str.from(1).to(-2) #=> "ell"
   def to(position)
     self[0..position]
   end
 
+  # Returns the first character. If a limit is supplied, returns a substring
+  # from the beginning of the string until it reaches the limit value. If the
+  # given limit is greater than or equal to the string length, returns self.
+  #
+  #   str = "hello"
+  #   str.first    #=> "h"
+  #   str.first(1) #=> "h"
+  #   str.first(2) #=> "he"
+  #   str.first(0) #=> ""
+  #   str.first(6) #=> "hello"
   def first(limit = 1)
     if limit == 0
       ''
@@ -23,6 +84,16 @@ class String
     end
   end
 
+  # Returns the last character of the string. If a limit is supplied, returns a substring
+  # from the end of the string until it reaches the limit value (counting backwards). If
+  # the given limit is greater than or equal to the string length, returns self.
+  #
+  #   str = "hello"
+  #   str.last    #=> "o"
+  #   str.last(1) #=> "o"
+  #   str.last(2) #=> "lo"
+  #   str.last(0) #=> ""
+  #   str.last(6) #=> "hello"
   def last(limit = 1)
     if limit == 0
       ''
diff --git a/activesupport/lib/active_support/core_ext/string/conversions.rb b/activesupport/lib/active_support/core_ext/string/conversions.rb
index 9084bbee32..022b376aec 100644
--- a/activesupport/lib/active_support/core_ext/string/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/string/conversions.rb
@@ -15,6 +15,12 @@ class String
     end
   end
 
+  # Converts a string to a Date value.
+  #
+  #   "1-1-2012".to_date   #=> Sun, 01 Jan 2012
+  #   "01/01/2012".to_date #=> Sun, 01 Jan 2012
+  #   "2012-12-13".to_date #=> Thu, 13 Dec 2012
+  #   "12/13/2012".to_date #=> ArgumentError: invalid date
   def to_date
     unless blank?
       date_values = ::Date._parse(self, false).values_at(:year, :mon, :mday)
@@ -23,6 +29,12 @@ class String
     end
   end
 
+  # Converts a string to a DateTime value.
+  #
+  #   "1-1-2012".to_datetime            #=> Sun, 01 Jan 2012 00:00:00 +0000
+  #   "01/01/2012 23:59:59".to_datetime #=> Sun, 01 Jan 2012 23:59:59 +0000
+  #   "2012-12-13 12:50".to_datetime    #=> Thu, 13 Dec 2012 12:50:00 +0000
+  #   "12/13/2012".to_datetime          #=> ArgumentError: invalid date
   def to_datetime
     unless blank?
       date_values = ::Date._parse(self, false).
diff --git a/activesupport/lib/active_support/core_ext/string/exclude.rb b/activesupport/lib/active_support/core_ext/string/exclude.rb
index 5e184ec1b3..114bcb87f0 100644
--- a/activesupport/lib/active_support/core_ext/string/exclude.rb
+++ b/activesupport/lib/active_support/core_ext/string/exclude.rb
@@ -1,5 +1,10 @@
 class String
-  # The inverse of <tt>String#include?</tt>. Returns true if the string does not include the other string.
+  # The inverse of <tt>String#include?</tt>. Returns true if the string
+  # does not include the other string.
+  #
+  #   "hello".exclude? "lo" #=> false
+  #   "hello".exclude? "ol" #=> true
+  #   "hello".exclude? ?h   #=> false
   def exclude?(string)
     !include?(string)
   end
diff --git a/activesupport/lib/active_support/core_ext/string/filters.rb b/activesupport/lib/active_support/core_ext/string/filters.rb
index 32a37296d5..2478f42290 100644
--- a/activesupport/lib/active_support/core_ext/string/filters.rb
+++ b/activesupport/lib/active_support/core_ext/string/filters.rb
@@ -5,7 +5,6 @@ class String
   # the string, and then changing remaining consecutive whitespace
   # groups into one space each.
   #
-  # Examples:
   #   %{ Multi-line
   #      string }.squish                   # => "Multi-line string"
   #   " foo   bar    \n   \t   boo".squish # => "foo bar boo"
diff --git a/activesupport/lib/active_support/core_ext/string/inflections.rb b/activesupport/lib/active_support/core_ext/string/inflections.rb
index 049ffe7986..070bfd7af6 100644
--- a/activesupport/lib/active_support/core_ext/string/inflections.rb
+++ b/activesupport/lib/active_support/core_ext/string/inflections.rb
@@ -13,7 +13,6 @@ class String
   # the singular form will be returned if <tt>count == 1</tt>.
   # For any other value of +count+ the plural will be returned.
   #
-  # ==== Examples
   #   'post'.pluralize             # => "posts"
   #   'octopus'.pluralize          # => "octopi"
   #   'sheep'.pluralize            # => "sheep"
@@ -46,7 +45,6 @@ class String
   # in the string. It raises a NameError when the name is not in CamelCase
   # or is not initialized.  See ActiveSupport::Inflector.constantize
   #
-  # Examples
   #   'Module'.constantize  # => Module
   #   'Class'.constantize   # => Class
   #   'blargle'.constantize # => NameError: wrong constant name blargle
@@ -58,7 +56,6 @@ class String
   # in the string. It returns nil when the name is not in CamelCase
   # or is not initialized.  See ActiveSupport::Inflector.safe_constantize
   #
-  # Examples
   #   'Module'.safe_constantize  # => Module
   #   'Class'.safe_constantize   # => Class
   #   'blargle'.safe_constantize # => nil
@@ -140,8 +137,6 @@ class String
 
   # Replaces special characters in a string so that it may be used as part of a 'pretty' URL.
   #
-  # ==== Examples
-  #
   #   class Person
   #     def to_param
   #       "#{id}-#{name.parameterize}"
@@ -194,7 +189,6 @@ class String
   # +separate_class_name_and_id_with_underscore+ sets whether
   # the method should put '_' between the name and 'id'.
   #
-  # Examples
   #   'Message'.foreign_key        # => "message_id"
   #   'Message'.foreign_key(false) # => "messageid"
   #   'Admin::Post'.foreign_key    # => "post_id"
diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb
index 215ba87ca9..6bda970e40 100644
--- a/activesupport/lib/active_support/core_ext/string/output_safety.rb
+++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb
@@ -14,7 +14,6 @@ class ERB
     # In your ERB templates, use this method to escape any unsafe content. For example:
     #   <%=h @person.name %>
     #
-    # ==== Example:
     #   puts html_escape('is a > 0 & a < 10?')
     #   # => is a &gt; 0 &amp; a &lt; 10?
     def html_escape(s)
@@ -37,7 +36,6 @@ class ERB
 
     # A utility method for escaping HTML without affecting existing escaped entities.
     #
-    # ==== Examples
     #   html_escape_once('1 < 2 &amp; 3')
     #   # => "1 &lt; 2 &amp; 3"
     #