1 files changed, 14 insertions, 2 deletions

diff --git a/activerecord/lib/active_record/acts/list.rb b/activerecord/lib/active_record/acts/list.rb
index 6d235967c6..87bb1280e1 100644
--- a/activerecord/lib/active_record/acts/list.rb
+++ b/activerecord/lib/active_record/acts/list.rb
@@ -77,7 +77,8 @@ module ActiveRecord
         def insert_at(position = 1)
           insert_at_position(position)
         end
-
+        
+        # Swap positions with the next lower item, if one exists.
         def move_lower
           return unless lower_item
 
@@ -87,6 +88,7 @@ module ActiveRecord
           end
         end
         
+        # Swap positions with the next higher item, if one exists.
         def move_higher
           return unless higher_item
 
@@ -96,6 +98,8 @@ module ActiveRecord
           end
         end
         
+        # Move to the bottom of the list. If the item is already in the list, the items below it have their
+        # position adjusted accordingly.
         def move_to_bottom
           return unless in_list?
           acts_as_list_class.transaction do
@@ -104,6 +108,8 @@ module ActiveRecord
           end
         end
         
+        # Move to the top of the list. If the item is already in the list, the items above it have their
+        # position adjusted accordingly.
         def move_to_top
           return unless in_list?
           acts_as_list_class.transaction do
@@ -111,31 +117,36 @@ module ActiveRecord
             assume_top_position
           end
         end
-  
+        
         def remove_from_list
           decrement_positions_on_lower_items if in_list?
         end
 
+        # Increase the position of this item without adjusting the rest of the list.
         def increment_position
           return unless in_list?
           update_attribute position_column, self.send(position_column).to_i + 1
         end
   
+        # Decrease the position of this item without adjusting the rest of the list.
         def decrement_position
           return unless in_list?
           update_attribute position_column, self.send(position_column).to_i - 1
         end
   
+        # Return true if this object is the first in the list.
         def first?
           return false unless in_list?
           self.send(position_column) == 1
         end
         
+        # Return true if this object is the last in the list.
         def last?
           return false unless in_list?
           self.send(position_column) == bottom_position_in_list
         end
         
+        # Return the next higher item in the list.
         def higher_item
           return nil unless in_list?
           acts_as_list_class.find(:first, :conditions =>
@@ -143,6 +154,7 @@ module ActiveRecord
           )
         end
 
+        # Return the next lower item in the list.
         def lower_item
           return nil unless in_list?
           acts_as_list_class.find(:first, :conditions =>