1 files changed, 50 insertions, 0 deletions
diff --git a/aspectj-attic/testing-src/org/aspectj/testing/compare/adapters/package.html b/aspectj-attic/testing-src/org/aspectj/testing/compare/adapters/package.html
new file mode 100644
index 000000000..c2d839ed1
--- /dev/null
+++ b/aspectj-attic/testing-src/org/aspectj/testing/compare/adapters/package.html
@@ -0,0 +1,50 @@
+<html>
+<body>
+These adapters facilitate using the GenericTreeNode
+comparison utilities on different types of trees.
+The classes currently in this package support Swing
+<code>TreeNode</code> and AspectJ compiler <code>StructureNode</code>.
+
+<p>
+<code>Structure</code> supports a command-line interface for
+compiling <code>StructureNode</code> trees using 
+<code>AspectJCompiler</code> and saving 
+or loading them using serialization.  Once loaded, two trees
+can be compared using the <code>GenericTreeNode.traverse(..)</code> method,
+providing it the appropriate visitors and comparators to implement
+a comparison of the expected and actual structure trees and
+report on any differences.  (This is used to validate that
+changes to the structure tree are backwards compatible with
+trees from previous compiles, since the structure tree is
+effectively exported from the compiler to the IDE tools.)
+
+<p>
+If you want to support new trees,
+<code>GenericTreeNodeFactoryI</code> is the interface to implement.
+It specifies a factory to provide a <code>Comparator</code> based
+on a given pair to be compared. This means that you can
+use (or generate) comparators based on specific pairs.
+Usually you will implement only for the target type,
+so your factory may be final and always return a 
+singleton <code>Comparator.</code>
+<p>
+The <code>SubTypeComparator</code> implements a <code>Comparator</code>
+container that acts as a <code>Comparator</code> by delegating to
+contained <code>Comparator</code>s registered along with the class of the input
+they accept.  This permits you to write type-specific
+<code>Comparator</code>s for heterogeneous trees.  It does require
+both members of the comparison be assignable to the
+target class.
+
+<p> 
+<code>StructureGenericTreeNodeFactory</code> is an implementation of
+<code>GenericTreeNodeFactoryI</code> for StructureNode trees.  It
+contains comparator classes for <code>RelationNode</code>, <code>LinkNode,</code>
+and <code>ProgramElementNode</code>, 
+combined using a <code>SubTypeComparator.</code>
+<p> 
+<code>JTreeNodeGenericTreeNodeFactory</code> is an implementation of
+<code>GenericTreeNodeFactoryI</code>  for Swing <code>TreeNode</code>'s, done only
+for testing purposes.
+</body>
+</html>