Improving documentation...

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

1 files changed, 35 insertions, 31 deletions

diff --git a/activerecord/lib/active_record/acts/tree.rb b/activerecord/lib/active_record/acts/tree.rb
index f05bbe9a78..c01b6f7ab7 100644
--- a/activerecord/lib/active_record/acts/tree.rb
+++ b/activerecord/lib/active_record/acts/tree.rb
@@ -1,39 +1,43 @@
 module ActiveRecord
-  module Acts
-    # Including this mixin if you want to model a tree structure by providing a parent association and an children 
-    # association. This mixin assumes that you have a column called parent_id
-    # 
-    #   class Category < ActiveRecord::Base
-    #     include ActiveRecord::Mixins::Tree
-    #   end
-    #   
-    #   Example : 
-    #   root
-    #    \_ child1 
-    #         \_ sub-child1
-    #
-    #   root      = Category.create("name" => "root")
-    #   child1      = root.children.create("name" => "child1")
-    #   subchild1   = child1.children.create("name" => "subchild1")
-    #
-    #   root.parent # => nil
-    #   child1.parent # => root
-    #   root.children # => [child1]
-    #   root.children.first.children.first # => subchild1
-    module Tree
+  module Acts #:nodoc:
+    module Tree #:nodoc:
       def self.append_features(base)
         super        
         base.extend(ClassMethods)              
       end  
-    end
-    
-    module ClassMethods
-      def acts_as_tree(options = {})
-        configuration = { :foreign_key => "parent_id", :order => nil }
-        configuration.update(options) if options.is_a?(Hash)
-        
-        belongs_to :parent, :class_name => name, :foreign_key => configuration[:foreign_key]
-        has_many :children, :class_name => name, :foreign_key => configuration[:foreign_key], :order => configuration[:order], :dependent => true
+
+      # Specify this act if you want to model a tree structure by providing a parent association and an children 
+      # association. This act assumes that requires that you have a foreign key column, which by default is called parent_id.
+      # 
+      #   class Category < ActiveRecord::Base
+      #     acts_as_tree :order => "name"
+      #   end
+      #   
+      #   Example : 
+      #   root
+      #    \_ child1 
+      #         \_ sub-child1
+      #
+      #   root      = Category.create("name" => "root")
+      #   child1      = root.children.create("name" => "child1")
+      #   subchild1   = child1.children.create("name" => "subchild1")
+      #
+      #   root.parent # => nil
+      #   child1.parent # => root
+      #   root.children # => [child1]
+      #   root.children.first.children.first # => subchild1
+      module ClassMethods
+        # Configuration options are:
+        #
+        # * <tt>foreign_key</tt> - specifies the column name to use for track of the tree (default: parent_id)
+        # * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
+        def acts_as_tree(options = {})
+          configuration = { :foreign_key => "parent_id", :order => nil }
+          configuration.update(options) if options.is_a?(Hash)
+          
+          belongs_to :parent, :class_name => name, :foreign_key => configuration[:foreign_key]
+          has_many :children, :class_name => name, :foreign_key => configuration[:foreign_key], :order => configuration[:order], :dependent => true
+        end
       end
     end
   end