documentation project patches, closes #7342, #7319, #7316, #7190 [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6470 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

2 files changed, 16 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/acts/list.rb b/activerecord/lib/active_record/acts/list.rb
index 87bb1280e1..cacf6a81f6 100644
--- a/activerecord/lib/active_record/acts/list.rb
+++ b/activerecord/lib/active_record/acts/list.rb
@@ -74,6 +74,7 @@ module ActiveRecord
       # lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return true if that chapter is
       # the first in the list of all chapters.
       module InstanceMethods
+        # Insert the item at the given position (defaults to the top position of 1).
         def insert_at(position = 1)
           insert_at_position(position)
         end
@@ -118,6 +119,7 @@ module ActiveRecord
           end
         end
         
+        # Removes the item from the list.
         def remove_from_list
           decrement_positions_on_lower_items if in_list?
         end
@@ -162,6 +164,7 @@ module ActiveRecord
           )
         end
 
+        # Test if this record is in a list
         def in_list?
           !send(position_column).nil?
         end
@@ -178,21 +181,26 @@ module ActiveRecord
           # Overwrite this method to define the scope of the list changes
           def scope_condition() "1" end
 
+          # Returns the bottom position number in the list.
+          #   bottom_position_in_list    # => 2
           def bottom_position_in_list(except = nil)
             item = bottom_item(except)
             item ? item.send(position_column) : 0
           end
 
+          # Returns the bottom item
           def bottom_item(except = nil)
             conditions = scope_condition
             conditions = "#{conditions} AND #{self.class.primary_key} != #{except.id}" if except
             acts_as_list_class.find(:first, :conditions => conditions, :order => "#{position_column} DESC")
           end
 
+          # Forces item to assume the bottom position in the list.
           def assume_bottom_position
             update_attribute(position_column, bottom_position_in_list(self).to_i + 1)
           end
   
+          # Forces item to assume the top position in the list.
           def assume_top_position
             update_attribute(position_column, 1)
           end
@@ -227,6 +235,7 @@ module ActiveRecord
            )
           end
 
+          # Increments position (<tt>position_column</tt>) of all items in the list.
           def increment_positions_on_all_items
             acts_as_list_class.update_all(
               "#{position_column} = (#{position_column} + 1)",  "#{scope_condition}"
diff --git a/activerecord/lib/active_record/acts/tree.rb b/activerecord/lib/active_record/acts/tree.rb
index 44432d4741..b92587e521 100644
--- a/activerecord/lib/active_record/acts/tree.rb
+++ b/activerecord/lib/active_record/acts/tree.rb
@@ -70,16 +70,23 @@ module ActiveRecord
           nodes
         end
 
+        # Returns the root node of the tree.
         def root
           node = self
           node = node.parent while node.parent
           node
         end
 
+        # Returns all siblings of the current node.
+        #
+        #   subchild1.siblings # => [subchild2]
         def siblings
           self_and_siblings - [self]
         end
 
+        # Returns all siblings and a reference to the current node.
+        #
+        #   subchild1.self_and_siblings # => [subchild1, subchild2]
         def self_and_siblings
           parent ? parent.children : self.class.roots
         end