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

Conflicts:
	guides/source/migrations.md

8 files changed, 22 insertions, 35 deletions

diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb
index 907fe70522..704998301c 100644
--- a/activerecord/lib/active_record/autosave_association.rb
+++ b/activerecord/lib/active_record/autosave_association.rb
@@ -32,8 +32,6 @@ module ActiveRecord
   # autosave callbacks are executed. Placing your callbacks after
   # associations is usually a good practice.
   #
-  # == Examples
-  #
   # === One-to-one Example
   #
   #   class Post
diff --git a/activerecord/lib/active_record/counter_cache.rb b/activerecord/lib/active_record/counter_cache.rb
index c53b7b3e78..81f92db271 100644
--- a/activerecord/lib/active_record/counter_cache.rb
+++ b/activerecord/lib/active_record/counter_cache.rb
@@ -79,16 +79,17 @@ module ActiveRecord
         where(primary_key => id).update_all updates.join(', ')
       end
 
-      # Increment a number field by one, usually representing a count.
+      # Increment a numeric field by one, via a direct SQL update.
       #
-      # This is used for caching aggregate values, so that they don't need to be computed every time.
-      # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
-      # shown it would have to run an SQL query to find how many posts and comments there are.
+      # This method is used primarily for maintaining counter_cache columns used to
+      # store aggregate values. For example, a DiscussionBoard may cache posts_count
+      # and comments_count to avoid running an SQL query to calculate the number of
+      # posts and comments there are each time it is displayed.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be incremented.
-      # * +id+ - The id of the object that should be incremented.
+      # * +id+ - The id of the object that should be incremented or an Array of ids.
       #
       # ==== Examples
       #
@@ -98,14 +99,15 @@ module ActiveRecord
         update_counters(id, counter_name => 1)
       end
 
-      # Decrement a number field by one, usually representing a count.
+      # Decrement a numeric field by one, via a direct SQL update.
       #
-      # This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
+      # This works the same as increment_counter but reduces the column value by
+      # 1 instead of increasing it.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be decremented.
-      # * +id+ - The id of the object that should be decremented.
+      # * +id+ - The id of the object that should be decremented or an Array of ids.
       #
       # ==== Examples
       #
diff --git a/activerecord/lib/active_record/integration.rb b/activerecord/lib/active_record/integration.rb
index 23c272ef12..7bdc1bd4c6 100644
--- a/activerecord/lib/active_record/integration.rb
+++ b/activerecord/lib/active_record/integration.rb
@@ -29,8 +29,6 @@ module ActiveRecord
 
     # Returns a cache key that can be used to identify this record.
     #
-    # ==== Examples
-    #
     #   Product.new.cache_key     # => "products/new"
     #   Product.find(5).cache_key # => "products/5" (updated_at not available)
     #   Person.find(5).cache_key  # => "people/5-20071224150000" (updated_at available)
diff --git a/activerecord/lib/active_record/query_cache.rb b/activerecord/lib/active_record/query_cache.rb
index 38e18b32a4..df8654e5c1 100644
--- a/activerecord/lib/active_record/query_cache.rb
+++ b/activerecord/lib/active_record/query_cache.rb
@@ -4,6 +4,7 @@ module ActiveRecord
   class QueryCache
     module ClassMethods
       # Enable the query cache within the block if Active Record is configured.
+      # If it's not, it will execute the given block.
       def cache(&block)
         if ActiveRecord::Base.connected?
           connection.cache(&block)
@@ -13,6 +14,7 @@ module ActiveRecord
       end
 
       # Disable the query cache within the block if Active Record is configured.
+      # If it's not, it will execute the given block.
       def uncached(&block)
         if ActiveRecord::Base.connected?
           connection.uncached(&block)
diff --git a/activerecord/lib/active_record/querying.rb b/activerecord/lib/active_record/querying.rb
index 45f6a78428..5ddcaee6be 100644
--- a/activerecord/lib/active_record/querying.rb
+++ b/activerecord/lib/active_record/querying.rb
@@ -26,14 +26,13 @@ module ActiveRecord
     # MySQL specific terms will lock you to using that particular database engine or require you to
     # change your call if you switch engines.
     #
-    # ==== Examples
     #   # A simple SQL query spanning multiple tables
     #   Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id"
-    #   > [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
+    #   # => [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
     #
     #   # You can use the same string replacement techniques as you can with ActiveRecord#find
     #   Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date]
-    #   > [#<Post:0x36bff9c @attributes={"title"=>"The Cheap Man Buys Twice"}>, ...]
+    #   # => [#<Post:0x36bff9c @attributes={"title"=>"The Cheap Man Buys Twice"}>, ...]
     def find_by_sql(sql, binds = [])
       logging_query_plan do
         result_set = connection.select_all(sanitize_sql(sql), "#{name} Load", binds)
@@ -57,8 +56,6 @@ module ActiveRecord
     #
     # * +sql+ - An SQL statement which should return a count query from the database, see the example below.
     #
-    # ==== Examples
-    #
     #   Product.count_by_sql "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id = c.id"
     def count_by_sql(sql)
       logging_query_plan do
diff --git a/activerecord/lib/active_record/relation/calculations.rb b/activerecord/lib/active_record/relation/calculations.rb
index 99e77e007a..ccc14dddeb 100644
--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/activerecord/lib/active_record/relation/calculations.rb
@@ -76,18 +76,17 @@ module ActiveRecord
     #
     #       values = Person.group('last_name').maximum(:age)
     #       puts values["Drake"]
-    #       => 43
+    #       # => 43
     #
     #       drake  = Family.find_by_last_name('Drake')
     #       values = Person.group(:family).maximum(:age) # Person belongs_to :family
     #       puts values[drake]
-    #       => 43
+    #       # => 43
     #
     #       values.each do |family, max_age|
     #       ...
     #       end
     #
-    # Examples:
     #   Person.calculate(:count, :all) # The same as Person.count
     #   Person.average(:age) # SELECT AVG(age) FROM people...
     #
@@ -124,8 +123,6 @@ module ActiveRecord
     # the plucked column names, if they can be deduced. Plucking an SQL fragment
     # returns String values by default.
     #
-    # Examples:
-    #
     #   Person.pluck(:id)
     #   # SELECT people.id FROM people
     #   # => [1, 2, 3]
@@ -182,8 +179,6 @@ module ActiveRecord
 
     # Pluck all the ID's for the relation using the table's primary key
     #
-    # Examples:
-    #
     #   Person.ids # SELECT people.id FROM people
     #   Person.joins(:companies).ids # SELECT people.id FROM people INNER JOIN companies ON companies.person_id = people.id
     def ids
diff --git a/activerecord/lib/active_record/relation/spawn_methods.rb b/activerecord/lib/active_record/relation/spawn_methods.rb
index 352dee3826..d417e82548 100644
--- a/activerecord/lib/active_record/relation/spawn_methods.rb
+++ b/activerecord/lib/active_record/relation/spawn_methods.rb
@@ -12,9 +12,6 @@ module ActiveRecord
 
     # Merges in the conditions from <tt>other</tt>, if <tt>other</tt> is an <tt>ActiveRecord::Relation</tt>.
     # Returns an array representing the intersection of the resulting records with <tt>other</tt>, if <tt>other</tt> is an array.
-    #
-    # ==== Examples
-    #
     #   Post.where(published: true).joins(:comments).merge( Comment.where(spam: false) )
     #   # Performs a single join query with both where conditions.
     #
@@ -29,7 +26,6 @@ module ActiveRecord
     #   # => Post.where(published: true).joins(:comments)
     #
     # This is mainly intended for sharing common conditions between multiple associations.
-    #
     def merge(other)
       if other.is_a?(Array)
         to_a & other
@@ -51,11 +47,8 @@ module ActiveRecord
 
     # Removes from the query the condition(s) specified in +skips+.
     #
-    # Example:
-    #
     #   Post.order('id asc').except(:order)                  # discards the order condition
     #   Post.where('id > 10').order('id asc').except(:where) # discards the where condition but keeps the order
-    #
     def except(*skips)
       result = Relation.new(klass, table, values.except(*skips))
       result.default_scoped = default_scoped
@@ -65,11 +58,8 @@ module ActiveRecord
 
     # Removes any condition from the query other than the one(s) specified in +onlies+.
     #
-    # Example:
-    #
     #   Post.order('id asc').only(:where)         # discards the order condition
     #   Post.order('id asc').only(:where, :order) # uses the specified order
-    #
     def only(*onlies)
       result = Relation.new(klass, table, values.slice(*onlies))
       result.default_scoped = default_scoped
diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb
index eaa4aa7086..3259dbbd80 100644
--- a/activerecord/lib/active_record/schema.rb
+++ b/activerecord/lib/active_record/schema.rb
@@ -29,11 +29,16 @@ module ActiveRecord
   # ActiveRecord::Schema is only supported by database adapters that also
   # support migrations, the two features being very similar.
   class Schema < Migration
+
+    # Returns the migrations paths.
+    #
+    #   ActiveRecord::Schema.new.migrations_paths
+    #   # => ["db/migrate"] # Rails migration path by default.
     def migrations_paths
       ActiveRecord::Migrator.migrations_paths
     end
 
-    def define(info, &block)
+    def define(info, &block) # :nodoc:
       instance_eval(&block)
 
       unless info[:version].blank?