1 files changed, 40 insertions, 0 deletions
diff --git a/src/proguard/classfile/visitor/package.html b/src/proguard/classfile/visitor/package.html
new file mode 100644
index 0000000..d3be40c
--- /dev/null
+++ b/src/proguard/classfile/visitor/package.html
@@ -0,0 +1,40 @@
+<body>
+This package contains interfaces and classes for processing class files from
+the <code>{@link proguard.classfile proguard.classfile}</code> package using
+the <i>visitor pattern</i>. Cfr., for instance, "Design Patterns, Elements of
+Reusable OO Software", by Gamma, Helm, Johnson, and Vlissider.
+<p>
+Why the visitor pattern? Class files frequently contain lists of elements of
+various mixed types: class items, constant pool entries, attributes,...
+These lists and types are largely fixed; they won't change much in future
+releases of the Java class file specifications. On the other hand, the kinds
+of operations that we may wish to perform on the class files may change and
+expand. We want to separate the objects and the operations performed upon them.
+This is a good place to use the visitor pattern.
+<p>
+Visitor interfaces avoid having to do series of <code>instanceof</code> tests
+on the elements of a list, followed by type casts and the proper operations.
+Every list element is a visitor accepter. When its <code>accept</code> method
+is called by a visitor, it calls its corresponding <code>visitX</code> method
+in the visitor, passing itself as an argument. This technique is called
+double-dispatch.
+<p>
+As already mentioned, the main advantage is avoiding lots of
+<code>instanceof</code> tests and type casts. Also, implementing a visitor
+interface ensures you're handling all possible visitor accepter types. Each
+type has its own method, which you simply have to implement.
+<p>
+A disadvantage is that the visitor methods always get the same names, specified
+by the visitor interface. These names aren't descriptive at all, making code
+harder to read. It's the visitor classes that describe the operations now.
+<p>
+Also, the visitor methods always have the same parameters and return values, as
+specified by the visitor interfaces. Passing additional parameters is done by
+means of extra fields in the visitor, which is somewhat of a kludge.
+<p>
+Because objects (the visitor accepters) and the operations performed upon them
+(the visitors) are now separated, it becomes harder to associate some state
+with the objects. For convenience, we always provide an extra <i>visitor
+info</i> field in visitor accepters, in which visitors can put any temporary
+information they want.
+</body>