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

12 files changed, 82 insertions, 37 deletions

diff --git a/activemodel/lib/active_model/callbacks.rb b/activemodel/lib/active_model/callbacks.rb
index 257644b3fa..e7aad17021 100644
--- a/activemodel/lib/active_model/callbacks.rb
+++ b/activemodel/lib/active_model/callbacks.rb
@@ -2,11 +2,11 @@ require 'active_support/core_ext/array/wrap'
 require 'active_support/callbacks'
 
 module ActiveModel
-  # == Active Model Call Backs
+  # == Active Model Callbacks
   # 
   # Provides an interface for any class to have Active Record like callbacks.
   # 
-  # Like the Active Record methods, the call back chain is aborted as soon as
+  # Like the Active Record methods, the callback chain is aborted as soon as
   # one of the methods in the chain returns false.
   #
   # First, extend ActiveModel::Callbacks from the class you are creating:
@@ -15,13 +15,13 @@ module ActiveModel
   #     extend ActiveModel::Callbacks
   #   end
   # 
-  # Then define a list of methods that you want call backs attached to:
+  # Then define a list of methods that you want callbacks attached to:
   # 
   #   define_model_callbacks :create, :update
   # 
   # This will provide all three standard callbacks (before, around and after) around
   # both the :create and :update methods. To implement, you need to wrap the methods 
-  # you want call backs on in a block so that the call backs get a chance to fire:
+  # you want callbacks on in a block so that the callbacks get a chance to fire:
   # 
   #   def create
   #     _run_create_callbacks do
@@ -61,7 +61,7 @@ module ActiveModel
     #
     #   define_model_callbacks :initializer, :only => :after
     # 
-    # Note, the <tt>:only => <type></tt> hash will apply to all call backs defined on
+    # Note, the <tt>:only => <type></tt> hash will apply to all callbacks defined on
     # that method call.  To get around this you can call the define_model_callbacks
     # method as many times as you need.
     # 
@@ -72,8 +72,8 @@ module ActiveModel
     # Would create +after_create+, +before_update+ and +around_destroy+ methods only.
     # 
     # You can pass in a class to before_<type>, after_<type> and around_<type>, in which
-    # case the call back will call that class's <action>_<type> method passing the object
-    # that the call back is being called on.
+    # case the callback will call that class's <action>_<type> method passing the object
+    # that the callback is being called on.
     # 
     #   class MyModel
     #     extend ActiveModel::Callbacks
@@ -84,7 +84,7 @@ module ActiveModel
     # 
     #   class AnotherClass
     #     def self.before_create( obj )
-    #       # obj is the MyModel instance that the call back is being called on
+    #       # obj is the MyModel instance that the callback is being called on
     #     end
     #   end
     #     
diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index a82ce1bee0..4c80863e3a 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -4,7 +4,7 @@ require 'active_support/hash_with_indifferent_access'
 require 'active_support/core_ext/object/duplicable'
 
 module ActiveModel
-  # == Active Model Call Backs
+  # == Active Model Dirty
   #
   # Provides a way to track changes in your object in the same way as 
   # Active Record does.
diff --git a/activemodel/lib/active_model/validations/acceptance.rb b/activemodel/lib/active_model/validations/acceptance.rb
index 26b12b504b..77c401e0cc 100644
--- a/activemodel/lib/active_model/validations/acceptance.rb
+++ b/activemodel/lib/active_model/validations/acceptance.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Acceptance Validator
   module Validations
     class AcceptanceValidator < EachValidator
       def initialize(options)
@@ -22,29 +24,42 @@ module ActiveModel
     end
 
     module HelperMethods
-      # Encapsulates the pattern of wanting to validate the acceptance of a terms of service check box (or similar agreement). Example:
+      # Encapsulates the pattern of wanting to validate the acceptance of a 
+      # terms of service check box (or similar agreement). Example:
       #
       #   class Person < ActiveRecord::Base
       #     validates_acceptance_of :terms_of_service
       #     validates_acceptance_of :eula, :message => "must be abided"
       #   end
       #
-      # If the database column does not exist, the +terms_of_service+ attribute is entirely virtual. This check is
-      # performed only if +terms_of_service+ is not +nil+ and by default on save.
+      # If the database column does not exist, the +terms_of_service+ attribute 
+      # is entirely virtual. This check is performed only if +terms_of_service+
+      # is not +nil+ and by default on save.
       #
       # Configuration options:
-      # * <tt>:message</tt> - A custom error message (default is: "must be accepted").
-      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
-      # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default is true).
-      # * <tt>:accept</tt> - Specifies value that is considered accepted.  The default value is a string "1", which
-      #   makes it easy to relate to an HTML checkbox. This should be set to +true+ if you are validating a database
-      #   column, since the attribute is typecast from "1" to +true+ before validation.
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
-      #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
-      #   method, proc or string should return or evaluate to a true or false value.
+      # * <tt>:message</tt> - A custom error message (default is: "must be 
+      #   accepted").
+      # * <tt>:on</tt> - Specifies when this validation is active (default is
+      #   <tt>:save</tt>, other options are <tt>:create</tt> and 
+      #   <tt>:update</tt>).
+      # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default
+      #   is true).
+      # * <tt>:accept</tt> - Specifies value that is considered accepted. 
+      #   The default value is a string "1", which makes it easy to relate to
+      #   an HTML checkbox. This should be set to +true+ if you are validating 
+      #   a database column, since the attribute is typecast from "1" to +true+
+      #   before validation.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
+      #   or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
+      #   method, proc or string should return or evaluate to a true or false 
+      #   value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to 
+      #   determine if the validation should not occur (for example, 
+      #   <tt>:unless => :skip_validation</tt>, or 
+      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).
+      #   The method, proc or string should return or evaluate to a true or 
+      #   false value.
       def validates_acceptance_of(*attr_names)
         validates_with AcceptanceValidator, _merge_attributes(attr_names)
       end
diff --git a/activemodel/lib/active_model/validations/confirmation.rb b/activemodel/lib/active_model/validations/confirmation.rb
index 51445343f2..5e13db7491 100644
--- a/activemodel/lib/active_model/validations/confirmation.rb
+++ b/activemodel/lib/active_model/validations/confirmation.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Confirmation Validator
   module Validations
     class ConfirmationValidator < EachValidator
       def validate_each(record, attribute, value)
@@ -13,33 +15,45 @@ module ActiveModel
     end
 
     module HelperMethods
-      # Encapsulates the pattern of wanting to validate a password or email address field with a confirmation. Example:
+      # Encapsulates the pattern of wanting to validate a password or email 
+      # address field with a confirmation. For example:
       #
       #   Model:
       #     class Person < ActiveRecord::Base
       #       validates_confirmation_of :user_name, :password
-      #       validates_confirmation_of :email_address, :message => "should match confirmation"
+      #       validates_confirmation_of :email_address, 
+      #                                 :message => "should match confirmation"
       #     end
       #
       #   View:
       #     <%= password_field "person", "password" %>
       #     <%= password_field "person", "password_confirmation" %>
       #
-      # The added +password_confirmation+ attribute is virtual; it exists only as an in-memory attribute for validating the password.
-      # To achieve this, the validation adds accessors to the model for the confirmation attribute. NOTE: This check is performed
-      # only if +password_confirmation+ is not +nil+, and by default only on save. To require confirmation, make sure to add a presence
-      # check for the confirmation attribute:
+      # The added +password_confirmation+ attribute is virtual; it exists only 
+      # as an in-memory attribute for validating the password. To achieve this,
+      # the validation adds accessors to the model for the confirmation 
+      # attribute.
+      # 
+      # NOTE: This check is performed only if +password_confirmation+ is not 
+      # +nil+, and by default only on save. To require confirmation, make sure
+      # to add a presence check for the confirmation attribute:
       #
       #   validates_presence_of :password_confirmation, :if => :password_changed?
       #
       # Configuration options:
-      # * <tt>:message</tt> - A custom error message (default is: "doesn't match confirmation").
-      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
-      #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
+      # * <tt>:message</tt> - A custom error message (default is: "doesn't match
+      #   confirmation").
+      # * <tt>:on</tt> - Specifies when this validation is active (default is
+      #   <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
+      #   or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
+      #   method, proc or string should return or evaluate to a true or false 
+      #   value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to 
+      #   determine if the validation should not occur (e.g. 
+      #   <tt>:unless => :skip_validation</tt>, or 
+      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_confirmation_of(*attr_names)
         validates_with ConfirmationValidator, _merge_attributes(attr_names)
diff --git a/activemodel/lib/active_model/validations/exclusion.rb b/activemodel/lib/active_model/validations/exclusion.rb
index 2ee78f5dd2..599623368f 100644
--- a/activemodel/lib/active_model/validations/exclusion.rb
+++ b/activemodel/lib/active_model/validations/exclusion.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Exclusion Validator
   module Validations
     class ExclusionValidator < EachValidator
       def check_validity!
diff --git a/activemodel/lib/active_model/validations/format.rb b/activemodel/lib/active_model/validations/format.rb
index c34c860d4d..3b57d4fd77 100644
--- a/activemodel/lib/active_model/validations/format.rb
+++ b/activemodel/lib/active_model/validations/format.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Format Validator
   module Validations
     class FormatValidator < EachValidator
       def validate_each(record, attribute, value)
diff --git a/activemodel/lib/active_model/validations/inclusion.rb b/activemodel/lib/active_model/validations/inclusion.rb
index 446646d247..e9940dbbf0 100644
--- a/activemodel/lib/active_model/validations/inclusion.rb
+++ b/activemodel/lib/active_model/validations/inclusion.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Inclusion Validator
   module Validations
     class InclusionValidator < EachValidator
       def check_validity!
diff --git a/activemodel/lib/active_model/validations/length.rb b/activemodel/lib/active_model/validations/length.rb
index d7218f4f52..dc191d3150 100644
--- a/activemodel/lib/active_model/validations/length.rb
+++ b/activemodel/lib/active_model/validations/length.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Length Validator
   module Validations
     class LengthValidator < EachValidator
       MESSAGES  = { :is => :wrong_length, :minimum => :too_short, :maximum => :too_long }.freeze
diff --git a/activemodel/lib/active_model/validations/numericality.rb b/activemodel/lib/active_model/validations/numericality.rb
index 062b4cd17f..c2e7223939 100644
--- a/activemodel/lib/active_model/validations/numericality.rb
+++ b/activemodel/lib/active_model/validations/numericality.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model Numericality Validator
   module Validations
     class NumericalityValidator < EachValidator
       CHECKS = { :greater_than => :>, :greater_than_or_equal_to => :>=,
diff --git a/activemodel/lib/active_model/validations/presence.rb b/activemodel/lib/active_model/validations/presence.rb
index b319f4834b..e36bee8115 100644
--- a/activemodel/lib/active_model/validations/presence.rb
+++ b/activemodel/lib/active_model/validations/presence.rb
@@ -1,6 +1,8 @@
 require 'active_support/core_ext/object/blank'
 
 module ActiveModel
+
+  # == Active Model Presence Validator
   module Validations
     class PresenceValidator < EachValidator
       def validate(record)
diff --git a/activemodel/lib/active_model/validations/validates.rb b/activemodel/lib/active_model/validations/validates.rb
index 57162996c2..0674640925 100644
--- a/activemodel/lib/active_model/validations/validates.rb
+++ b/activemodel/lib/active_model/validations/validates.rb
@@ -1,6 +1,8 @@
 require 'active_support/core_ext/hash/slice'
 
 module ActiveModel
+
+  # == Active Model validates method
   module Validations
     module ClassMethods
       # This method is a shortcut to all default validators and any custom
diff --git a/activemodel/lib/active_model/validations/with.rb b/activemodel/lib/active_model/validations/with.rb
index 6dbde5bfad..a2e870d714 100644
--- a/activemodel/lib/active_model/validations/with.rb
+++ b/activemodel/lib/active_model/validations/with.rb
@@ -1,4 +1,6 @@
 module ActiveModel
+
+  # == Active Model validates_with method
   module Validations
     module HelperMethods
       private