Improvements

Author: electricessence

Node.cs

@@ -1,8 +1,7 @@
+using Open.Disposable;
 using System;
-using System.Collections.Generic;
-using System.Linq;
 using System.Collections;
-using Open.Disposable;
+using System.Collections.Generic;
 
 namespace Open.Hierarchy
 {
@@ -124,10 +123,15 @@ public Node<T> Root
 
 		object IHaveRoot.Root => Root;
 
-		internal void Teardown()
+		public void Teardown()
 		{
 			Value = default(T);
 			Detatch(); // If no parent then this does nothing...
+			TeardownChildren();
+		}
+
+		public void TeardownChildren()
+		{
 			foreach (var c in _children)
 			{
 				c._parent = null; // Don't initiate a 'Detach' (which does a lookup) since we are clearing here;
@@ -136,12 +140,21 @@ internal void Teardown()
 			_children.Clear();
 		}
 
-		internal void Recycle(Factory factory)
+		public void Recycle(Factory factory)
 		{
-			if (factory == null) throw new ArgumentNullException("factory");
+			if (factory == null)
+				throw new ArgumentNullException("factory");
 
 			Value = default(T);
 			Detatch(); // If no parent then this does nothing...
+			RecycleChildren(factory);
+		}
+
+		public void RecycleChildren(Factory factory)
+		{
+			if (factory == null)
+				throw new ArgumentNullException("factory");
+
 			foreach (var c in _children)
 			{
 				c._parent = null; // Don't initiate a 'Detach' (which does a lookup) since we are clearing here;
@@ -150,7 +163,6 @@ internal void Recycle(Factory factory)
 			_children.Clear();
 		}
 
-
 		/// <summary>
 		/// Used for mapping a tree of evaluations which do not have access to their parent nodes.
 		/// </summary>
@@ -173,6 +185,13 @@ protected override void OnDispose(bool calledExplicitly)
 
 			ConcurrentQueueObjectPool<Node<T>> Pool;
 
+			public Node<T> GetBlankNode()
+			{
+				AssertIsAlive();
+
+				return Pool?.Take();
+			}
+
 			public void Recycle(Node<T> n)
 			{
 				AssertIsAlive();

Readme.md

@@ -0,0 +1,20 @@
+# Open.Hierarchy
+
+## ```Node<T>```
+One of the important abilities of ```Node<T>``` and its supporting classes is to allow for creating and modifying tree structures that only have a parent to child relationship.  It's important to ensure that a node cannot occur multiple times in a tree but an instance of its value can occur any number of times. This facilitates potential 'value sub-trees' that can have dupicate references but not duplicate instances.  By using ```Node<T>``` as a container, a single instance can exist multiple times in a tree but still be uniquely indentifyable by its position.
+
+## ```Node<T>.Factory```
+
+### Blank Instance
+Calling ```.GetBlankNode()``` will retrieve a blank node from the underlying object pool or create a new one.
+
+### Mapping
+Calling ```.Map(root)``` generates node hierarchy map based upon if the root or any of its children implement ```IParent```. 
+
+### Cloning
+Calling ```.Clone(node)``` creates a copy of the node map.
+
+### Recycling
+```Node<T>``` instances can be recycled by calling the ```Factory.Recycle(node)``` method.  The node itself and its children are torn down and recycled to an object pool.
+
+***WARNING:*** The ```Factory.Recycle(node)``` method is the one point of potential trouble if multiple references are retained.  It must be used with care.