rubytree 0.6.2 → 0.7.0

data/API-CHANGES

@@ -0,0 +1,42 @@
+= API Changes in RubyTree
+
+This file documents various API level changes that have been made to the RubyTree package.
+
+Note: API level changes are expected to reduce dramatically after the 1.x release.  In most cases, an alternative will
+be provided to ensure relatively smooth transition to the new APIs.
+
+== Release 0.7.0 Changes
+
+- Converted all exceptions thrown on invalid method arguments to from 'RuntimeError' to 'ArgumentError'.  This impacts the
+  following methods:
+
+  - {Tree::TreeNode#initialize}
+  - {Tree::TreeNode#add}
+  - {Tree::TreeNode#[]}
+  - {Tree::BinaryTreeNode#add}
+
+- Added {Tree::TreeNode#level} as an alias for {Tree::TreeNode#nodeDepth}
+
+- Added new methods {Tree::TreeNode#in_degree} and {Tree::TreeNode#out_degree} to report the node's degree stats
+
+- {Tree::TreeNode#isOnlyChild?} now returns +true+ for a root node.
+
+- {Tree::TreeNode#nextSibling} and {Tree::TreeNode#previousSibling} now return +nil+ for a root node.
+
+- {Tree::TreeNode#add} and {Tree::TreeNode#<<} now throw an ArgumentError exception if a +nil+ node is passed as an argument.
+
+- Added new methods {Tree::TreeNode#to_json} and {Tree::TreeNode::json_create} to convert to/from the JSON format.
+  Thanks to Dirk[http://github.com/railsbros-dirk] for this change.
+
+== Release 0.6.1 Changes
+
+- Deprecated the {Tree::TreeNode#depth} method as it was returning an incorrect depth value.  Have introduced a new replacement
+  method {Tree::TreeNode#nodeDepth} which returns the correct result.
+
+
+
+
+# Local Variables:
+# mode: text
+# coding: utf-8-unix
+# End:

data/COPYING

@@ -27,3 +27,17 @@ WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWIS
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 $Id$
+
+
+
+
+
+
+
+
+
+
+# Local Variables:
+# mode: text
+# coding: utf-8-unix
+# End:

data/History.txt

@@ -1,3 +1,24 @@
+=== 0.7.0 / 2010-05-03
+
+* Added new methods to report the degree statistics of a node.
+
+* Added a convenience method alias 'level' to 'nodeDepth'.
+
+* Converted the exceptions thrown on invalid arguments to 'ArgumentError' instead of 'RuntimeError'.
+
+* Converted the documentation to Yard format.
+
+* Added new methods for converting from/to JSON formats.  Thanks to Dirk Breuer[http://github.com/railsbros-dirk] for
+  this fork[http://github.com/galaxycats/].
+
+* Added a separate API-CHANGES documentation file.
+
+* Added fixes for root related edge conditions to 'isOnlyChild?', 'nextSibling', 'previousSibling' and 'remove' methods.
+
+* Removed the 'ChangeLog' file as this can now be generated from the git logs.
+
+* Other minor code cleanup.
+
 === 0.6.2 / 2010-01-30
 
 * Updated the documentation.

data/Manifest.txt

@@ -1,8 +1,8 @@
 COPYING
-ChangeLog
 History.txt
 Manifest.txt
 README
+API-CHANGES
 Rakefile
 TODO
 lib/tree.rb

data/README

@@ -1,4 +1,4 @@
-= rubytree
+= RubyTree
    __       _           _
    /__\_   _| |__  _   _| |_ _ __ ___  ___
   / \// | | | '_ \| | | | __| '__/ _ \/ _ \
@@ -6,8 +6,9 @@
  \/ \_/\__,_|_.__/ \__, |\__|_|  \___|\___|
                   |___/
 
-  Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta (anupamsg at gmail dot com)
-  http://rubytree.rubyforge.org
+Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta (anupamsg at gmail dot com)
+
+http://rubytree.rubyforge.org
 
 == DESCRIPTION:
 
@@ -52,7 +53,7 @@ As an example, the following code-snippet implements this tree structure:
  child1 = root_node["CHILD1"]
  grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
 
- # ..... Now lets retrieve siblings of the current node as an array.
+ # ..... Lets retrieve siblings of the current node as an array.
  siblings_of_child1 = child1.siblings
 
  # ..... Lets retrieve immediate children of the root node as an array.
@@ -68,10 +69,16 @@ As an example, the following code-snippet implements this tree structure:
 == REQUIREMENTS:
 
 * Ruby 1.8+  (http://www.ruby-lang.org)
-* Hoe (http://seattlerb.rubyforge.org/hoe/Hoe.html) Rubygem
 
 * Optional but recommended:
   * structured_warnings (http://github.com/schmidt/structured_warnings) Rubygem
+  * Yard (http://yardoc.org) Rubygem for the documentation
+  * JSON (http://flori.github.com/json) Rubygem for converting to/from the JSON format
+
+* Development dependencies (not required for installing the gem):
+  * Hoe (http://seattlerb.rubyforge.org/hoe/Hoe.html) Rubygem
+  * gemcutter (http://gemcutter.org/gems/gemcutter) Rubygem
+  * Rubyforge (http://codeforpeople.rubyforge.org/rubyforge) Rubygem
 
 == INSTALL:
 
@@ -119,20 +126,63 @@ From a command line/terminal prompt, you can issue the following command to view
 
     ri Tree::TreeNode
 
-Documentation on the web is available at:
+Documentation for the latest released version is available at:
 
 http://rubytree.rubyforge.org/rdoc
 
+Documentation for the latest git HEAD is available at:
+
+http://rdoc.info/projects/evolve75/RubyTree
+
+Note that the documentation is formatted for Yard (http://yardoc.org).
+
 == DEVELOPERS:
 
+You can download the latest released source code using the tar or zip version as mentioned above in the installation
+section.
+
+Alternatively, you can checkout the latest commit/revision from the version control system.  Note that RubyTree's
+primary SCM[http://en.wikipedia.org/wiki/Source_Code_Management] is on git[http://git-scm.com] and is
+also mirrored on github[http://www.github.com].
+
+=== Using the Git repository
+
+For checking out from the primary Git repository, use the following command:
+
+  $ git clone git://rubyforge.org/rubytree.git
+
+The Git repository is available for browsing on the web at: http://fisheye2.atlassian.com/browse/rubytree
+
+=== Using the Git repository on http://github.com
+
+For cloning the git repository, use one of the following commands:
+
+  $ git clone git://github.com/evolve75/RubyTree.git
+
+or
+  $ git clone http://github.com/evolve75/RubyTree.git
+
+The git repository is available on the web at: http://github.com/evolve75/RubyTree
+
+=== Setting up the development environment
+
 After checking out the source, run:
 
   $ rake newb
 
 This task will install any missing dependencies, run the tests/specs, and generate the RDoc.
 
-Note that you need to have the Rubygem 'Hoe' (http://seattlerb.rubyforge.org/hoe/Hoe.html) to successfully run the rake
-tasks.
+Note that you need to have the Rubygem Hoe[http://seattlerb.rubyforge.org/hoe/Hoe.html] to successfully run the rake
+tasks.  Installing Hoe may also install additional pre-requisite gems.  See the REQUIREMENTS section in this document for
+details.
+
+For generating the documentation, it is strongly suggested that the Yard[http://yardoc.org] gem be installed.
+
+== ACKNOWLEDGMENTS:
+
+I would like to acknowledge the following contributors for helping improve RubyTree:
+
+1. Dirk Breuer (http://github.com/railsbros-dirk) for contributing the JSON conversion code.
 
 == LICENSE:
 
@@ -163,3 +213,8 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 
 (Document Revision: $Revision$ by $Author$)
+
+# Local Variables:
+# mode: text
+# coding: utf-8-unix
+# End:

data/Rakefile

@@ -43,16 +43,20 @@ task :default => :gem
 # Use Hoe to define the rake tasks.
 begin
   require 'hoe'
+  Hoe.plugin :yard
+
   Hoe.spec PKG_NAME do
     # The GemSpec settings
     self.rubyforge_name = PKG_NAME
     developer "Anupam Sengupta", "anupamsg@gmail.com"
-    self.extra_rdoc_files           = ['README', 'COPYING', 'ChangeLog']
+
     self.url                        =  "http://rubytree.rubyforge.org"
     self.readme_file                = 'README'
-    # Set the RDoc Options.
-    self.spec_extras[:rdoc_options] = ['--main', 'README', '--line-numbers']
-    self.spec_extras[:has_rdoc]     = true
+
+    # Set the Yard Options
+    extra_docs                      = ["COPYING", "API-CHANGES"]
+    extra_docs.each { |file| self.yard_files << file }
+    self.yard_options = ["--files", extra_docs.join(",") ]
 
     # Now the publishing settings
     self.remote_rdoc_dir            = 'rdoc'
@@ -65,13 +69,15 @@ begin
     self.post_install_message       = <<MSGEND
 ========================================================================
 
- Thank you for installing #{PKG_NAME.capitalize}.
+ Thank you for installing #{PKG_NAME}.
 
- Please note that a few APIs have been deprecated since Version 0.6.1
+ Please note that a few APIs have been deprecated since Version 0.6.1.
 
  Specifically, the 'Tree::TreeNode#depth' method is now deprecated, and
  a new nodeDepth() method has been introduced.
 
+ Details of the API changes are documented in the API-CHANGES file.
+
 ========================================================================
 MSGEND
 

data/TODO

@@ -1,24 +1,52 @@
 # -*- mode: org; coding: utf-8-unix; -*-
 
-* TODO Convert all method names to the canonical /^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/ pattern
-  See Roodi report at http://getcaliper.com/caliper/tool?tool=roodi&repo=git://github.com/evolve75/RubyTree.git
-* TODO Fix the TreeNode#root method to return nil for root's root.
-* TODO Fix the marshal_load method.  This probably needs to be a class method.
-* TODO Fix the semantic inconsistency between the TreeNode#first|lastSibling method and the siblings method w.r.t. the root
-* TODO Create the basic UML diagrams and upload to the Site
-  DEADLINE: <2010-01-04 Mon>
 
-* DONE Fix bug # [[http://rubyforge.org/tracker/index.php%3Ffunc%3Ddetail&aid%3D22535&group_id%3D1215&atid%3D4793][22535]]: The method Tree::TreeNode#depth is a misnomer.  The current definition actually provides the height function.
-  DEADLINE: <2010-01-09 Sat> CLOSED: [2010-01-03 Sun 22:15]
-
-* TODO Add a YAML export method to the TreeNode class.
-
-* DONE Get the version control moved from CVS to Subversion (request submitted to RubyForge)
-  CLOSED: [2010-01-02 Sat 17:58]
-
-* DONE Add logic in Rakefile to read the file list from Manifest.txt file.
+* R0.7.0
+*** TODO Start using signed tags from R0.7.0
+*** DONE Add a check in the Tree::TreeNode.add method to prevent addition of nil child nodes
+    CLOSED: [2010-02-23 Tue 23:07]
+*** DONE Fix the edge condition for Tree::TreeNode.isOnlyChild? when the root node is the receiver.
+    CLOSED: [2010-02-23 Tue 22:03]
+    There really is no good default to this situation.  We will return 'true' simply because there is no other sibling
+    to a root.  However, a good case can be made that a root node does not have any parent either.
+*** DONE Add a convenience 'level' method to the TreeNode class (will be an alias to nodeDepth)
+    CLOSED: [2010-02-21 Sun 01:02]
+*** DONE Add a API-CHANGES file to document the various API changes made till date
+    CLOSED: [2010-01-31 Sun 00:52]
+*** DONE Add new methods to return the degree counts of the receiver node (in-degree and out-degree)
+    CLOSED: [2010-01-30 Sat 23:56]
+
+* R0.8.0
+*** TODO Convert all method names to the canonical /^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/ pattern
+    See Roodi report at http://getcaliper.com/caliper/tool?tool=roodi&repo=git://github.com/evolve75/RubyTree.git
+*** TODO Fix the inconsistency of returning root as its first sibling, and returning a nil instead.  Ditto for last sibling.
+*** TODO fix the inconsistency of returning nil for the root, and an empty array for nodes which have no siblings.
+*** TODO We should perhaps return nil as root's root.
+*** TODO The semantic of length is probably unclear.  Should return the node_depth instead (or remove the method)
+    The current equivalence of length to size should also be removed.
+
+
+* Unplanned / Not assigned to any release
+*** TODO Fix the TreeNode#root method to return nil for root's root.
+*** TODO Fix the marshal_load method.  This probably needs to be a class method.
+*** TODO Fix the semantic inconsistency between the TreeNode#first|lastSibling method and the siblings method w.r.t. the root
+*** TODO Create the basic UML diagrams and upload to the Site
+    DEADLINE: <2010-01-04 Mon>
+
+*** DONE Fix bug # [[http://rubyforge.org/tracker/index.php%3Ffunc%3Ddetail&aid%3D22535&group_id%3D1215&atid%3D4793][22535]]: The method Tree::TreeNode#depth is a misnomer.  The current definition actually provides the height function.
+    DEADLINE: <2010-01-09 Sat> CLOSED: [2010-01-03 Sun 22:15]
+
+*** TODO Add a YAML export method to the TreeNode class.
+
+*** DONE Get the version control moved from CVS to Subversion (request submitted to RubyForge)
+    CLOSED: [2010-01-02 Sat 17:58]
+
+*** DONE Add logic in Rakefile to read the file list from Manifest.txt file.
   CLOSED: [2009-12-31 Thu 23:37]
+*** TODO Fix the inconsistency of returning root as its last sibling, and returning a nil array for siblings of the node
+*** TODO marshal_load method probably should be a class method.  It currently clobbers self.
+*** TODO Fix the inconsistency of returning root as its first/last sibling, and returning a nil array for siblings of the node
 
+$Id$
 
 
-$Id$

data/lib/tree.rb

@@ -44,39 +44,39 @@
 # This module provides a TreeNode class which is the primary class for representing
 # nodes in the tree.
 #
-# This module mixes in the Enumerable module, and also acts as the namespace for all
-# classes in RubyTree.
+# This module also acts as the namespace for all classes in the RubyTree package.
 module Tree
 
   # Rubytree Package Version
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 
   # == TreeNode Class Description
   #
-  # This class models the nodes for an N-ary tree data structue. The nodes are +named+
-  # and have a place-holder for the node data (i.e., `content' of the node). The node
+  # This class models the nodes for an *N-ary* tree data structue. The nodes are *named*
+  # and have a place-holder for the node data (i.e., _content_ of the node). The node
   # names are required to be *unique* within the tree.
   #
-  # The node content is not required to be unique across different nodes in the tree, and
+  # The node's _content_ is *not* required to be unique across different nodes in the tree, and
   # can be +nil+ as well.
   #
-  # The class provides various traversal methods to navigate the tree,
-  # methods to modify contents of the node or to change position of the node in the tree
-  # and methods to change structure of the tree.
+  # The class provides various methods to navigate the tree, traverse the structure,
+  # modify contents of the node, change position of the node in the tree,
+  # and to make structural changes to the tree.
   #
-  # A node can have any number of child nodes attached to it and hence can be used to create N-ary trees.
+  # A node can have any number of *child* nodes attached to it and hence can be used to create N-ary trees.
   # Access to the child nodes can be made in order (with the conventional left to right access), or
   # randomly.
   #
-  # The node also provides direct access to its parent and other superior parents in the path to
-  # root of the tree.  In addition, a node can also access its sibling nodes, if present.
-  # Note that while this implementation does not explicitly support directed graphs, the class itself makes
-  # no restrictions on associating a node's +CONTENT+ with multiple nodes in the tree.
+  # The node also provides direct access to its *parent* node as well as other superior parents in the path to
+  # root of the tree.  In addition, a node can also access its *sibling* nodes, if present.
+  #
+  # Note that while this implementation does not _explicitly_ support directed graphs, the class itself makes
+  # no restrictions on associating a node's *content* with multiple nodes in the tree.
   #
   #
   # == Example
   #
-  #  The following example implements this tree structure:
+  # The following example implements this tree structure:
   #
   #                    +------------+
   #                    |    ROOT    |
@@ -92,30 +92,36 @@ module Tree
   #    | GRANDCHILD 1  |
   #    +---------------+
   #
-  # require 'tree'
-  #
-  # root_node = Tree::TreeNode.new("ROOT", "Root Content")
-  #
-  # root_node << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
-  #
-  # root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
+  #    # ..... Example starts.
+  #    require 'tree'                 # Load the library
   #
-  # root_node.printTree
+  #    # ..... Create the root node first.  Note that every node has a name and an optional content payload.
+  #    root_node = Tree::TreeNode.new("ROOT", "Root Content")
   #
-  # child1       = root_node["CHILD1"]
+  #    # ..... Now insert the child nodes.  Note that you can "chain" the child insertions for a given path to any depth.
+  #    root_node << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
+  #    root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
   #
-  # grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
+  #    # ..... Lets print the representation to stdout.  This is primarily used for debugging purposes.
+  #    root_node.printTree
   #
-  # siblings_of_child1 = child1.siblings
+  #    # ..... Lets directly access children and grandchildren of the root.  The can be "chained" for a given path to any depth.
+  #    child1       = root_node["CHILD1"]
+  #    grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
   #
-  # children_of_root   = root_node.children
+  #    # ..... Now lets retrieve siblings of the current node as an array.
+  #    siblings_of_child1 = child1.siblings
   #
-  # # Process all nodes
+  #    # ..... Lets retrieve immediate children of the root node as an array.
+  #    children_of_root = root_node.children
   #
-  # root_node.each { |node| node.content.reverse }
+  #    # ..... This is a depth-first and L-to-R pre-ordered traversal.
+  #    root_node.each { |node| node.content.reverse }
   #
-  # root_node.remove!(child1) # Remove the child
+  #    # ..... Lets remove a child node from the root node.
+  #    root_node.remove!(child1)
   #
+  # @author Anupam Sengupta
   class TreeNode
     include Enumerable
 
@@ -125,31 +131,40 @@ module Tree
     # Content of this node.  Can be +nil+.
     attr_accessor :content
 
-    # Parent of this node.  Will be +nil+ for root nodes.
+    # Parent of this node.  Will be +nil+ for a root node.
     attr_reader   :parent
 
 
-    # Constructor which expects the name of the node.
-    # Name of the node is expected to be unique across the tree.
+    # Creates a new node with a name and optional content.
+    # The node name is expected to be unique within the tree.
     #
-    # The content can be of any type, defaults to +nil+.
+    # The content can be of any type, and defaults to +nil+.
+    #
+    # @param [Object] name Name of the node.  Usual usage is to pass a String.
+    # @param [Object] content Content of the node.
+    #
+    # @raise [ArgumentError] Raised if the node name is empty.
     def initialize(name, content = nil)
-      raise "Node name HAS to be provided" if name == nil
-      @name = name
-      @content = content
-      self.setAsRoot!
+      raise ArgumentError, "Node name HAS to be provided!" if name == nil
+      @name, @content = name, content
 
+      self.setAsRoot!
       @childrenHash = Hash.new
       @children = []
     end
 
     # Returns a copy of the receiver node, with its parent and children links removed.
     # The original node remains attached to its tree.
+    #
+    # @return [Tree::TreeNode] A copy of the receiver node.
     def detached_copy
       Tree::TreeNode.new(@name, @content ? @content.clone : nil)
     end
 
-    # Print the string representation of this node.  This is primary for debugging purposes.
+    # Returns string representation of the receiver node.
+    # This method is primarily meant for debugging purposes.
+    #
+    # @return [String] A string representation of the node.
     def to_s
       "Node Name: #{@name}" +
         " Content: " + (@content || "<Empty>") +
@@ -162,6 +177,8 @@ module Tree
     # (the first element is the immediate parent of the receiver).
     #
     # Returns +nil+ if the receiver is a root node.
+    #
+    # @return [Array, nil] An array of ancestors of the receiver node, or +nil+ if this is a root node.
     def parentage
       return nil if isRoot?
 
@@ -178,19 +195,26 @@ module Tree
     # Protected method to set the parent node for the receiver node.
     # This method should *NOT* be invoked by client code.
     #
-    # Returns the parent.
+    # @param [Tree::TreeNode] parent The parent node.
+    #
+    # @return [Tree::TreeNode] The parent node.
     def parent=(parent)         # :nodoc:
       @parent = parent
     end
 
-    # Convenience synonym for TreeNode#add method.
+    # Convenience synonym for {Tree::TreeNode#add} method.
     #
-    # This method allows an easy method to add node hierarchies to the tree
+    # This method allows an easy mechanism to add node hierarchies to the tree
     # on a given path via chaining the method calls to successive child nodes.
     #
-    # Example: <tt>root << child << grand_child</tt>
+    # @example Add a child and grand-child to the root
+    #   root << child << grand_child
     #
-    # Returns the added child node.
+    # @param [Tree::TreeNode] child the child node to add.
+    #
+    # @return [Tree::TreeNode] The added child node.
+    #
+    # @see Tree::TreeNode#add
     def <<(child)
       add(child)
     end
@@ -204,11 +228,18 @@ module Tree
     # the child is added as the last child ("right most") in the current set of
     # children of the receiver node.
     #
-    # Returns the added child node.
+    # @param [Tree::TreeNode] child The child node to add.
+    #
+    # @return [Tree::TreeNode] The added child node.
     #
-    # An exception is raised if another child node with the same name exists.
+    # @raise [RuntimeError] This exception is raised if another child node with the same
+    # name exists.
+    # @raise [ArgumentError] This exception is raised if a +nil+ node is passed as the argument.
+    #
+    # @see #<<
     def add(child)
-      raise "Child already added" if @childrenHash.has_key?(child.name)
+      raise ArgumentError, "Attempting to add a nil node" unless child
+      raise "Child #{child.name} already added!" if @childrenHash.has_key?(child.name)
 
       @childrenHash[child.name]  = child
       @children << child
@@ -218,32 +249,45 @@ module Tree
 
     # Removes the specified child node from the receiver node.
     #
-    # This method can also be used for *pruning* a subtree, in cases where the removed child node is
-    # the root of the subtree to be pruned.
+    # This method can also be used for *pruning* a sub-tree, in cases where the removed child node is
+    # the root of the sub-tree to be pruned.
+    #
+    # The removed child node is orphaned but accessible if an alternate reference exists.  If accessible via
+    # an alternate reference, the removed child will report itself as a root node for its sub-tree.
     #
-    # The removed child node is orphaned but accessible if an alternate reference exists.  If accesible via
-    # an alternate reference, the removed child will report itself as a root node for its subtree.
+    # @param [Tree::TreeNode] child The child node to remove.
     #
-    # Returns the child node.
+    # @return [Tree::TreeNode] The removed child node, or +nil+ if a +nil+ was passed in as argument.
+    #
+    # @see #removeFromParent!
+    # @see #removeAll!
     def remove!(child)
+      return nil unless child
+
       @childrenHash.delete(child.name)
       @children.delete(child)
-      child.setAsRoot! unless child == nil
-      return child
+      child.setAsRoot!
+      child
     end
 
     # Removes the receiver node from its parent.  The reciever node becomes the new root for its subtree.
     #
     # If this is the root node, then does nothing.
     #
-    # Returns self (the removed receiver node) if the operation is successful, and +nil+ otherwise.
+    # @return [Tree:TreeNode] +self+ (the removed receiver node) if the operation is successful, +nil+ otherwise.
+    #
+    # @see #removeAll!
     def removeFromParent!
       @parent.remove!(self) unless isRoot?
     end
 
-    # Removes all children from the receiver node.
+    # Removes all children from the receiver node.  If an indepedent reference exists to the child
+    # nodes, then these child nodes report themselves as roots after this operation.
     #
-    # Returns the receiver node.
+    # @return [Tree::TreeNode] The receiver node (+self+)
+    #
+    # @see #remove!
+    # @see #removeFromParent!
     def removeAll!
       for child in @children
         child.setAsRoot!
@@ -253,38 +297,56 @@ module Tree
       self
     end
 
-    # Returns +true+ if the receiver node has any associated content.
+    # Returns +true+ if the receiver node has content.
+    #
+    # @return [Boolean] +true+ if the node has content.
     def hasContent?
       @content != nil
     end
 
     # Protected method which sets the receiver node as a root node.
     #
-    # Returns +nil+.
+    # @return +nil+.
     def setAsRoot!              # :nodoc:
       @parent = nil
     end
 
     # Returns +true+ if the receiver is a root node.  Note that
     # orphaned children will also be reported as root nodes.
+    #
+    # @return [Boolean] +true+ if this is a root node.
     def isRoot?
       @parent == nil
     end
 
-    # Returns +true+ if the receiver node has any immediate child nodes.
+    # Returns +true+ if the receiver node has any child node.
+    #
+    # @return [Boolean] +true+ if child nodes exist.
+    #
+    # @see #isLeaf?
     def hasChildren?
       @children.length != 0
     end
 
     # Returns +true+ if the receiver node is a 'leaf' - i.e., one without
     # any children.
+    #
+    # @return [Boolean] +true+ if this is a leaf node.
+    #
+    # @see #hasChildren?
     def isLeaf?
       !hasChildren?
     end
 
-    # Returns an array of all the immediate children of the receiver node.
+    # Returns an array of all the immediate children of the receiver node.  The child nodes are ordered
+    # "left-to-right" in the returned array.
     #
     # If a block is given, yields each child node to the block traversing from left to right.
+    #
+    # @yield [child] Each child is passed to the block, if given
+    # @yieldparam [Tree::TreeNode] child Each child node.
+    #
+    # @return [Array<Tree::TreeNode>] An array of the child nodes, if no block is given.
     def children
       if block_given?
         @children.each {|child| yield child}
@@ -296,6 +358,8 @@ module Tree
     # Returns the first child of the receiver node.
     #
     # Will return +nil+ if no children are present.
+    #
+    # @return [Tree::TreeNode] The first child, or +nil+ if none is present.
     def firstChild
       children.first
     end
@@ -303,28 +367,49 @@ module Tree
     # Returns the last child of the receiver node.
     #
     # Will return +nil+ if no children are present.
+    #
+    # @return [Tree::TreeNode] The last child, or +nil+ if none is present.
     def lastChild
       children.last
     end
 
-    # Traverses every node (including the receiver node) from the (sub)tree
-    # by yielding the node to the specified block.
+    # Traverses each node (including the receiver node) of the (sub)tree rooted at this node
+    # by yielding the nodes to the specified block.
+    #
+    # The traversal is *depth-first* and from *left-to-right* in pre-ordered sequence.
+    #
+    # @yield [child] Each node is passed to the block.
+    # @yieldparam [Tree::TreeNode] child Each node.
     #
-    # The traversal is depth-first and from left to right in pre-ordered sequence.
-    def each &block             # :yields: node
+    # @see #preordered_each
+    # @see #breadth_each
+    def each(&block)             # :yields: node
       yield self
       children { |child| child.each(&block) }
     end
 
-    # Traverses the tree in a pre-ordered sequence.  This is equivalent to
-    # TreeNode#each
-    def preordered_each &block  # :yields: node
+    # Traverses the (sub)tree rooted at the receiver node in pre-ordered sequence.
+    # This is a synonym of {Tree::TreeNode#each}.
+    #
+    # @yield [child] Each child is passed to the block.
+    # @yieldparam [Tree::TreeNode] node Each node.
+    #
+    # @see #each
+    # @see #breadth_each
+    def preordered_each(&block)  # :yields: node
       each(&block)
     end
 
-    # Performs breadth first traversal of the tree starting at the receiver node. The
-    # traversal at a given level is from left to right.
-    def breadth_each &block
+    # Performs breadth-first traversal of the (sub)tree rooted at the receiver node. The
+    # traversal at a given level is from *left-to-right*.  The receiver node itself is the first
+    # node to be traversed.
+    #
+    # @yield [child] Each node is passed to the block.
+    # @yieldparam [Tree::TreeNode] node Each node.
+    #
+    # @see #preordered_each
+    # @see #breadth_each
+    def breadth_each(&block)
       node_queue = [self]       # Create a queue with self as the initial entry
 
       # Use a queue to do breadth traversal
@@ -336,23 +421,39 @@ module Tree
       end
     end
 
-    # Yields all leaf nodes from the receiver node to the specified block.
+    # Yields every leaf node of the (sub)tree rooted at the receiver node to the specified block.
     #
     # May yield this node as well if this is a leaf node.
-    # Leaf traversal is depth-first and left to right.
+    # Leaf traversal is *depth-first* and *left-to-right*.
+    #
+    # @yield [node] Each leaf node is passed to the block.
+    # @yieldparam [Tree::TreeNode] node Each leaf node.
+    #
+    # @see #each
+    # @see #breadth_each
     def each_leaf &block
       self.each { |node| yield(node) if node.isLeaf? }
     end
 
     # Returns the requested node from the set of immediate children.
     #
-    # If the argument is _numeric_, then the in-sequence array of children is
-    # accessed (see Tree#children).  If the argument is *NOT* _numeric_, then it
-    # is assumed to be *name* of the child node to be returned.
+    # If the argument is _numeric_, then the in-sequence array of children is accessed using
+    # the argument as the *index* (zero-based).
+    #
+    # If the argument is *NOT* _numeric_, then it is taken to be the *name* of the child node to be returned.
+    #
+    # An ArgumentError exception is raised if neither name nor an index is provided.
+    #
+    # @param [String|Number] name_or_index Name of the child, or its positional index in the array of child nodes.
+    #
+    # @return [Tree::TreeNode] the requested child node.  If the index in not in range, or the name is not
+    #        present, then a +nil+ is returned.
+    #
+    # @raise [ArgumentError] Raised if neither name nor index is provided.
     #
-    # Raises an exception is the requested child node is not found.
+    # @see #add
     def [](name_or_index)
-      raise "Name_or_index needs to be provided" if name_or_index == nil
+      raise ArgumentError, "Name_or_index needs to be provided!" if name_or_index == nil
 
       if name_or_index.kind_of?(Integer)
         @children[name_or_index]
@@ -366,16 +467,28 @@ module Tree
     # Size of the tree is defined as:
     #
     # Size:: Total number nodes in the subtree including the receiver node.
+    #
+    # @return [Number] Total number of nodes in this (sub)tree.
     def size
       @children.inject(1) {|sum, node| sum + node.size}
     end
 
-    # Convenience synonym for Tree#size
+    # Convenience synonym for {Tree::TreeNode#size}.
+    #
+    # @todo The semantic of length is probably unclear.  Should return the node depth instead
+    #       to reflect the path length.
+    #
+    # @deprecated This method name is ambiguous and may be removed.  Use TreeNode#size instead.
+    #
+    # @return [Number] The total number of nodes in this (sub)tree.
+    # @see #size
     def length
       size()
     end
 
-    # Pretty prints the tree starting with the receiver node.
+    # Pretty prints the (sub)tree rooted at the receiver node.
+    #
+    # @param [Number] level The indentation level (4 spaces) to start with.
     def printTree(level = 0)
 
       if isRoot?
@@ -396,47 +509,66 @@ module Tree
     # Returns root node for the (sub)tree to which the receiver node belongs.
     #
     # Note that a root node's root is itself (*beware* of any loop construct that may become infinite!)
-    #--
-    # TODO: We should perhaps return nil as root's root.
-    #++
+    #
+    # @todo We should perhaps return nil as root's root.
+    #
+    # @return [Tree::TreeNode] Root of the (sub)tree.
     def root
       root = self
       root = root.parent while !root.isRoot?
       root
     end
 
-    # Returns the first sibling for the receiver node. If this is the root node, returns
+    # Returns the first sibling of the receiver node. If this is the root node, then returns
     # itself.
     #
     # 'First' sibling is defined as follows:
     # First sibling:: The left-most child of the receiver's parent, which may be the receiver itself
-    #--
-    # TODO: Fix the inconsistency of returning root as its first sibling, and returning a
-    #       a nil array for siblings for the node.
-    #++
+    #
+    # @todo Fix the inconsistency of returning root as its first sibling, and returning
+    #       a +nil+ array for siblings of the node.
+    #
+    # @return [Tree::TreeNode] The first sibling node.
+    #
+    # @see #isFirstSibling?
+    # @see #lastSibling
     def firstSibling
       isRoot? ? self : parent.children.first
     end
 
-    # Returns true if the receiver node is the first sibling.
+    # Returns +true+ if the receiver node is the first sibling at its level.
+    #
+    # @return [Boolean] +true+ if this is the first sibling.
+    #
+    # @see #isLastSibling?
+    # @see #firstSibling
     def isFirstSibling?
       firstSibling == self
     end
 
-    # Returns the last sibling for the receiver node.  If this is the root node, returns
+    # Returns the last sibling of the receiver node.  If this is the root node, then returns
     # itself.
     #
     # 'Last' sibling is defined as follows:
     # Last sibling:: The right-most child of the receiver's parent, which may be the receiver itself
-    #--
-    # TODO: Fix the inconsistency of returning root as its last sibling, and returning a
-    #       a nil array for siblings for the node.
-    #++
+    #
+    # @todo Fix the inconsistency of returning root as its last sibling, and returning
+    #       a +nil+ array for siblings of the node.
+    #
+    # @return [Tree::TreeNode] The last sibling node.
+    #
+    # @see #isLastSibling?
+    # @see #firstSibling
     def lastSibling
       isRoot? ? self : parent.children.last
     end
 
-    # Returns true if the receivere node is the last sibling.
+    # Returns +true+ if the receiver node is the last sibling at its level.
+    #
+    # @return [Boolean] +true+ if this is the last sibling.
+    #
+    # @see #isFirstSibling?
+    # @see #lastSibling
     def isLastSibling?
       lastSibling == self
     end
@@ -445,10 +577,19 @@ module Tree
     #
     # If a block is provided, yields each of the sibling nodes to the block.
     # The root always has +nil+ siblings.
-    #--
-    # TODO: Fix the inconsistency of returning root as its first/last sibling, and returning a
-    #       a nil array for siblings for the node.
-    #++
+    #
+    # @todo Fix the inconsistency of returning root as its own first/last sibling, and returning
+    #       a +nil+ array for siblings of the same root node.
+    # @todo Also fix the inconsistency of returning +nil+ for a root node, and an empty array for nodes
+    #       which have no siblings.
+    #
+    # @yield [sibling] Each sibling is passed to the block.
+    # @yieldparam [Tree::TreeNode] sibling Each sibling node.
+    #
+    # @return [Array<Tree::TreeNode>] Array of siblings of this node.
+    #
+    # @see #firstSibling
+    # @see #lastSibling
     def siblings
       return nil if isRoot?
 
@@ -463,26 +604,44 @@ module Tree
       end
     end
 
-    # Returns true if the receiver node is the only child of its parent.
+    # Returns +true+ if the receiver node is the only child of its parent.
+    #
+    # As a special case, a root node will always return +true+.
+    #
+    # @return [Boolean] +true+ if this is the only child of its parent.
+    #
+    # @see #siblings
     def isOnlyChild?
-      parent.children.size == 1
+      isRoot? ? true : parent.children.size == 1
     end
 
     # Returns the next sibling for the receiver node.
     # The 'next' node is defined as the node to right of the receiver node.
     #
-    # Will return +nil+ if no subsequent node is present.
+    # Will return +nil+ if no subsequent node is present, or if the receiver is a root node.
+    #
+    # @return [Tree::treeNode] the next sibling node, if present.
+    #
+    # @see #previousSibling
+    # @see #siblings
     def nextSibling
+      return nil if isRoot?
       if myidx = parent.children.index(self)
         parent.children.at(myidx + 1)
       end
     end
 
-    # Returns the previous sibling for the receiver node.
-    # The 'previous' node is defined as the node to left of the receiver node.
+    # Returns the previous sibling of the receiver node.
+    # 'Previous' node is defined to be the node to left of the receiver node.
+    #
+    # Will return +nil+ if no predecessor node is present, or if the receiver is a root node.
+    #
+    # @return [Tree::treeNode] the previous sibling node, if present.
     #
-    # Will return nil if no predecessor node is present.
+    # @see #nextSibling
+    # @see #siblings
     def previousSibling
+      return nil if isRoot?
       if myidx = parent.children.index(self)
         parent.children.at(myidx - 1) if myidx > 0
       end
@@ -490,13 +649,20 @@ module Tree
 
     # Provides a comparision operation for the nodes.
     #
-    # Comparision is based on the natural character-set ordering of the *node name*.
+    # Comparision is based on the natural character-set ordering of the node name.
+    #
+    # @param [Tree::TreeNode] other The other node to compare against.
+    #
+    # @return [Number] +1 if this node is a 'successor', 0 if equal and -1 if this node is a 'predecessor'.
     def <=>(other)
       return +1 if other == nil
       self.name <=> other.name
     end
 
     # Freezes all nodes in the (sub)tree rooted at the receiver node.
+    #
+    # The nodes become immutable after this operation.  In effect, the entire tree's
+    # structure and contents become _read-only_ and cannot be changed.
     def freezeTree!
       each {|node| node.freeze}
     end
@@ -514,10 +680,10 @@ module Tree
     # Loads a marshalled dump of a tree and returns the root node of the
     # reconstructed tree. See the Marshal class for additional details.
     #
-    #--
-    # TODO: This method probably should be a class method.  It currently clobbers self
+    #
+    # @todo This method probably should be a class method.  It currently clobbers self
     #       and makes itself the root.
-    #++
+    #
     def marshal_load(dumped_tree_array)
       nodes = { }
       for node_hash in dumped_tree_array do
@@ -537,12 +703,73 @@ module Tree
       end
     end
 
+    # Creates a JSON representation of this node including all it's children.   This requires the JSON gem to be
+    # available, or else the operation fails with a warning message.
+    #
+    # @author Dirk Breuer (http://github.com/railsbros-dirk)
+    # @since 0.7.0
+    #
+    # @return The JSON representation of this subtree.
+    #
+    # @see Tree::TreeNode.json_create
+    # @see http://flori.github.com/json
+    def to_json(*a)
+      begin
+        require 'json'
+
+        json_hash = {
+          "name"         => name,
+          "content"      => content,
+          JSON.create_id => self.class.name
+        }
+
+        if hasChildren?
+          json_hash["children"] = children
+        end
+
+        return json_hash.to_json
+
+      rescue LoadError => e
+        warn "The JSON gem couldn't be loaded. Due to this we cannot serialize the tree to a JSON representation"
+      end
+    end
+
+    # Creates a Tree::TreeNode object instance from a given JSON Hash representation.  This requires the JSON gem to be
+    # available, or else the operation fails with a warning message.
+    #
+    # @author Dirk Breuer (http://github.com/railsbros-dirk)
+    # @since 0.7.0
+    #
+    # @param [Hash] json_hash The JSON hash to convert from.
+    #
+    # @return [Tree::TreeNode] The created tree.
+    #
+    # @see #to_json
+    # @see http://flori.github.com/json
+    def self.json_create(json_hash)
+      begin
+        require 'json'
+
+        node = new(json_hash["name"], json_hash["content"])
+
+        json_hash["children"].each do |child|
+          node << child
+        end if json_hash["children"]
+
+        return node
+      rescue LoadError => e
+        warn "The JSON gem couldn't be loaded. Due to this we cannot serialize the tree to a JSON representation."
+      end
+    end
+
     # Returns height of the (sub)tree from the receiver node.  Height of a node is defined as:
     #
     # Height:: Length of the longest downward path to a leaf from the node.
     #
     # - Height from a root node is height of the entire tree.
     # - The height of a leaf node is zero.
+    #
+    # @return [Number] Height of the node.
     def nodeHeight
       return 0 if isLeaf?
       1 + @children.collect { |child| child.nodeHeight }.max
@@ -552,13 +779,16 @@ module Tree
     #
     # Depth:: Length of the node's path to its root.  Depth of a root node is zero.
     #
-    # *Note* that the deprecated method Tree::TreeNode#depth was incorrectly computing this value.
-    # Please replace all calls to the old method with Tree::TreeNode#nodeDepth instead.
+    # 'level' is an alias for this method.
+    #
+    # @return [Number] Depth of this node.
     def nodeDepth
       return 0 if isRoot?
       1 + parent.nodeDepth
     end
 
+    alias level nodeDepth       # Aliased level() method to the nodeDepth().
+
     # Returns depth of the tree from the receiver node. A single leaf node has a depth of 1.
     #
     # This method is *DEPRECATED* and may be removed in the subsequent releases.
@@ -566,8 +796,13 @@ module Tree
     #
     # _height_ + 1 of the node, *NOT* the _depth_.
     #
-    # For correct and conventional behavior, please use Tree::TreeNode#nodeDepth and
-    # Tree::TreeNode#nodeHeight methods instead.
+    # For correct and conventional behavior, please use {Tree::TreeNode#nodeDepth} and
+    # {Tree::TreeNode#nodeHeight} methods instead.
+    #
+    # @return [Number] depth of the node.
+    # @deprecated This method returns an incorrect value.  Use the 'nodeDepth' method instead.
+    #
+    # @see #nodeDepth
     def depth
       begin
         require 'structured_warnings'   # To enable a nice way of deprecating of the depth method.
@@ -581,15 +816,41 @@ module Tree
       1 + @children.collect { |child| child.depth }.max
     end
 
-    # Returns breadth of the tree at the receiver node's  level.
+    # Returns breadth of the tree at the receiver node's level.
     # A single node without siblings has a breadth of 1.
     #
     # Breadth is defined to be:
-    # Breadth:: Number of sibling nodes to this node + 1 (this node itself), i.e., the number of children the parent of this node has.
+    # Breadth:: Number of sibling nodes to this node + 1 (this node itself),
+    # i.e., the number of children the parent of this node has.
+    #
+    # @return [Number] breadth of the node's level.
     def breadth
       isRoot? ? 1 : parent.children.size
     end
 
+    # Returns the incoming edge-count of the receiver node.
+    #
+    # In-degree is defined as:
+    # In-degree:: The number of edges arriving at the node (0 for root, 1 for all other nodes)
+    #
+    # - In-degree = 0 for a root or orphaned node
+    # - In-degree = 1 for a node which has a parent
+    #
+    # @return [Number] The in-degree of this node.
+    def in_degree
+      isRoot? ? 0 : 1
+    end
+
+    # Returns the outgoing edge-count of the receiver node.
+    #
+    # Out-degree is defined as:
+    # Out-degree:: The number of edges leaving the node (zero for leafs)
+    #
+    # @return [Number] The out-degree of this node.
+    def out_degree
+      isLeaf? ? 0 : children.size
+    end
+
     protected :parent=, :setAsRoot!, :createDumpRep
 
   end