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

actionmailer/lib/action_mailer/base.rb

@@ -395,7 +395,7 @@ def receive(raw_mail)
       end
 
       # Wraps an email delivery inside of Active Support Notifications instrumentation. This
-      # method is actually called by the <tt>Mail::Message</tt> object itself through a call back
+      # method is actually called by the <tt>Mail::Message</tt> object itself through a callback
       # when you call <tt>:deliver</tt> on the Mail::Message, calling +deliver_mail+ directly
       # and passing a Mail::Message will do nothing except tell the logger you sent the email.
       def deliver_mail(mail) #:nodoc:

activemodel/lib/active_model/callbacks.rb

@@ -2,11 +2,11 @@
 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 @@ def self.extended(base)
     #
     #   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 @@ def self.extended(base)
     # 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 @@ def self.extended(base)
     # 
     #   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
     #     

activemodel/lib/active_model/dirty.rb

@@ -4,7 +4,7 @@
 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.

activemodel/lib/active_model/validations/acceptance.rb

 module ActiveModel
+
+  # == Active Model Acceptance Validator
   module Validations
     class AcceptanceValidator < EachValidator
       def initialize(options)
@@ -22,29 +24,42 @@ def setup(klass)
     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

activemodel/lib/active_model/validations/confirmation.rb

 module ActiveModel
+
+  # == Active Model Confirmation Validator
   module Validations
     class ConfirmationValidator < EachValidator
       def validate_each(record, attribute, value)
@@ -13,33 +15,45 @@ def setup(klass)
     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)

activemodel/lib/active_model/validations/exclusion.rb

 module ActiveModel
+
+  # == Active Model Exclusion Validator
   module Validations
     class ExclusionValidator < EachValidator
       def check_validity!

activemodel/lib/active_model/validations/format.rb

 module ActiveModel
+
+  # == Active Model Format Validator
   module Validations
     class FormatValidator < EachValidator
       def validate_each(record, attribute, value)

activemodel/lib/active_model/validations/inclusion.rb

 module ActiveModel
+
+  # == Active Model Inclusion Validator
   module Validations
     class InclusionValidator < EachValidator
       def check_validity!

activemodel/lib/active_model/validations/length.rb

 module ActiveModel
+
+  # == Active Model Length Validator
   module Validations
     class LengthValidator < EachValidator
       MESSAGES  = { :is => :wrong_length, :minimum => :too_short, :maximum => :too_long }.freeze

activemodel/lib/active_model/validations/numericality.rb

 module ActiveModel
+
+  # == Active Model Numericality Validator
   module Validations
     class NumericalityValidator < EachValidator
       CHECKS = { :greater_than => :>, :greater_than_or_equal_to => :>=,

activemodel/lib/active_model/validations/presence.rb

 require 'active_support/core_ext/object/blank'
 
 module ActiveModel
+
+  # == Active Model Presence Validator
   module Validations
     class PresenceValidator < EachValidator
       def validate(record)

activemodel/lib/active_model/validations/validates.rb

 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

activemodel/lib/active_model/validations/with.rb

 module ActiveModel
+
+  # == Active Model validates_with method
   module Validations
     module HelperMethods
       private

activerecord/lib/active_record/aggregations.rb

 module ActiveRecord
+  # = Active Record Aggregations
   module Aggregations # :nodoc:
     extend ActiveSupport::Concern
 

activerecord/lib/active_record/attribute_methods.rb

 require 'active_support/core_ext/enumerable'
 
 module ActiveRecord
+  # = Active Record Attribute Methods
   module AttributeMethods #:nodoc:
     extend ActiveSupport::Concern
     include ActiveModel::AttributeMethods

activerecord/lib/active_record/autosave_association.rb

 require 'active_support/core_ext/array/wrap'
 
 module ActiveRecord
+  # = Active Record Autosave Association
+  # 
   # AutosaveAssociation is a module that takes care of automatically saving
   # your associations when the parent is saved. In addition to saving, it
   # also destroys any associations that were marked for destruction.

activerecord/lib/active_record/base.rb

@@ -21,6 +21,8 @@
 require 'active_record/errors'
 
 module ActiveRecord #:nodoc:
+  # = Active Record 
+  #
   # Active Record objects don't specify their attributes directly, but rather infer them from the table definition with
   # which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
   # is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain

activerecord/lib/active_record/callbacks.rb

 require 'active_support/core_ext/array/wrap'
 
 module ActiveRecord
+  # = Active Record Callbacks
+  # 
   # Callbacks are hooks into the lifecycle of an Active Record object that allow you to trigger logic
   # before or after an alteration of the object state. This can be used to make sure that associated and
   # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes

activerecord/lib/active_record/counter_cache.rb

 module ActiveRecord
+  # = Active Record Counter Cache
   module CounterCache
     # Resets one or more counter caches to their correct value using an SQL
     # count query.  This is useful when adding new counter caches, or if the

activerecord/lib/active_record/dynamic_finder_match.rb

 module ActiveRecord
+
+  # = Active Record Dynamic Finder Match
+  # 
+  # Provides dynamic attribute-based finders such as <tt>find_by_country</tt> 
+  # if, for example, the <tt>Person</tt> has an attribute with that name. 
   class DynamicFinderMatch
     def self.match(method)
       df_match = self.new(method)

activerecord/lib/active_record/dynamic_scope_match.rb

 module ActiveRecord
+
+  # = Active Record Dynamic Scope Match
+  # 
+  # Provides dynamic attribute-based scopes such as <tt>scoped_by_price(4.99)</tt>
+  # if, for example, the <tt>Product</tt> has an attribute with that name. You can
+  # chain more <tt>scoped_by_* </tt> methods after the other. It acts like a named
+  # scope except that it's dynamic.
   class DynamicScopeMatch
     def self.match(method)
       ds_match = self.new(method)

activerecord/lib/active_record/errors.rb

 module ActiveRecord
+
+  # = Active Record Errors
+  #
   # Generic Active Record exception class.
   class ActiveRecordError < StandardError
   end

activerecord/lib/active_record/migration.rb

@@ -29,11 +29,15 @@ def initialize(name)
     end
   end
 
-  # Migrations can manage the evolution of a schema used by several physical databases. It's a solution
-  # to the common problem of adding a field to make a new feature work in your local database, but being unsure of how to
-  # push that change to other developers and to the production server. With migrations, you can describe the transformations
-  # in self-contained classes that can be checked into version control systems and executed against another database that
-  # might be one, two, or five versions behind.
+  # Active Record Migrations
+  # 
+  # Migrations can manage the evolution of a schema used by several physical 
+  # databases. It's a solution to the common problem of adding a field to make
+  # a new feature work in your local database, but being unsure of how to
+  # push that change to other developers and to the production server. With 
+  # migrations, you can describe the transformations in self-contained classes
+  # that can be checked into version control systems and executed against 
+  # another database that might be one, two, or five versions behind.
   #
   # Example of a simple migration:
   #
@@ -47,10 +51,13 @@ def initialize(name)
   #     end
   #   end
   #
-  # This migration will add a boolean flag to the accounts table and remove it if you're backing out of the migration.
-  # It shows how all migrations have two class methods +up+ and +down+ that describes the transformations required to implement
-  # or remove the migration. These methods can consist of both the migration specific methods like add_column and remove_column,
-  # but may also contain regular Ruby code for generating data needed for the transformations.
+  # This migration will add a boolean flag to the accounts table and remove it 
+  # if you're backing out of the migration. It shows how all migrations have 
+  # two class methods +up+ and +down+ that describes the transformations 
+  # required to implement or remove the migration. These methods can consist
+  # of both the migration specific methods like add_column and remove_column,
+  # but may also contain regular Ruby code for generating data needed for the 
+  # transformations.
   #
   # Example of a more complex migration that also needs to initialize data:
   #
@@ -64,7 +71,9 @@ def initialize(name)
   #         t.integer  :position
   #       end
   #
-  #       SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
+  #       SystemSetting.create  :name => "notice", 
+  #                             :label => "Use notice?", 
+  #                             :value => 1
   #     end
   #
   #     def self.down
@@ -72,35 +81,49 @@ def initialize(name)
   #     end
   #   end
   #
-  # This migration first adds the system_settings table, then creates the very first row in it using the Active Record model
-  # that relies on the table. It also uses the more advanced create_table syntax where you can specify a complete table schema
-  # in one block call.
+  # This migration first adds the system_settings table, then creates the very 
+  # first row in it using the Active Record model that relies on the table. It
+  # also uses the more advanced create_table syntax where you can specify a 
+  # complete table schema in one block call.
   #
   # == Available transformations
   #
-  # * <tt>create_table(name, options)</tt> Creates a table called +name+ and makes the table object available to a block
-  #   that can then add columns to it, following the same format as add_column. See example above. The options hash is for
-  #   fragments like "DEFAULT CHARSET=UTF-8" that are appended to the create table definition.
+  # * <tt>create_table(name, options)</tt> Creates a table called +name+ and 
+  #   makes the table object available to a block that can then add columns to it,
+  #   following the same format as add_column. See example above. The options hash 
+  #   is for fragments like "DEFAULT CHARSET=UTF-8" that are appended to the create 
+  #   table definition.
   # * <tt>drop_table(name)</tt>: Drops the table called +name+.
-  # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ to +new_name+.
-  # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column to the table called +table_name+
+  # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ 
+  #   to +new_name+.
+  # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column 
+  #   to the table called +table_name+
   #   named +column_name+ specified to be one of the following types:
-  #   <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>,
-  #   <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be specified by passing an
-  #   +options+ hash like <tt>{ :default => 11 }</tt>. Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. <tt>{ :limit => 50, :null => false }</tt>)
-  #   -- see ActiveRecord::ConnectionAdapters::TableDefinition#column for details.
-  # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames a column but keeps the type and content.
-  # * <tt>change_column(table_name, column_name, type, options)</tt>:  Changes the column to a different type using the same
-  #   parameters as add_column.
-  # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+.
-  # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
-  #   <tt>:name</tt> and <tt>:unique</tt> (e.g. <tt>{ :name => "users_name_index", :unique => true }</tt>).
-  # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
+  #   <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, 
+  #   <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>,
+  #   <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be
+  #   specified by passing an +options+ hash like <tt>{ :default => 11 }</tt>. 
+  #   Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. 
+  #   <tt>{ :limit => 50, :null => false }</tt>) -- see 
+  #   ActiveRecord::ConnectionAdapters::TableDefinition#column for details.
+  # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames
+  #   a column but keeps the type and content.
+  # * <tt>change_column(table_name, column_name, type, options)</tt>:  Changes 
+  #   the column to a different type using the same parameters as add_column.
+  # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named 
+  #   +column_name+ from the table called +table_name+.
+  # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index 
+  #   with the name of the column. Other options include
+  #   <tt>:name</tt> and <tt>:unique</tt> (e.g. 
+  #   <tt>{ :name => "users_name_index", :unique => true }</tt>).
+  # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified 
+  #   by +index_name+.
   #
   # == Irreversible transformations
   #
-  # Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise
-  # an <tt>ActiveRecord::IrreversibleMigration</tt> exception in their +down+ method.
+  # Some transformations are destructive in a manner that cannot be reversed. 
+  # Migrations of that kind should raise an <tt>ActiveRecord::IrreversibleMigration</tt> 
+  # exception in their +down+ method.
   #
   # == Running migrations from within Rails
   #
@@ -110,13 +133,15 @@ def initialize(name)
   #   rails generate migration MyNewMigration
   #
   # where MyNewMigration is the name of your migration. The generator will
-  # create an empty migration file <tt>timestamp_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
-  # directory where <tt>timestamp</tt> is the UTC formatted date and time that the migration was generated.
+  # create an empty migration file <tt>timestamp_my_new_migration.rb</tt> 
+  # in the <tt>db/migrate/</tt> directory where <tt>timestamp</tt> is the 
+  # UTC formatted date and time that the migration was generated.
   #
   # You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
   # MyNewMigration.
   #
   # There is a special syntactic shortcut to generate migrations that add fields to a table.
+  #
   #   rails generate migration add_fieldname_to_tablename fieldname:string
   #
   # This will generate the file <tt>timestamp_add_fieldname_to_tablename</tt>, which will look like this:
@@ -191,9 +216,10 @@ def initialize(name)
   #
   # == Using a model after changing its table
   #
-  # Sometimes you'll want to add a column in a migration and populate it immediately after. In that case, you'll need
-  # to make a call to Base#reset_column_information in order to ensure that the model has the latest column data from
-  # after the new column was added. Example:
+  # Sometimes you'll want to add a column in a migration and populate it 
+  # immediately after. In that case, you'll need to make a call to 
+  # <tt>Base#reset_column_information</tt> in order to ensure that the model has the 
+  # latest column data from after the new column was added. Example:
   #
   #   class AddPeopleSalary < ActiveRecord::Migration
   #     def self.up