beef up the javadoc comments explaining what these classes do

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196759 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 20 insertions, 7 deletions

diff --git a/src/java/org/apache/fop/fo/FOInputHandler.java b/src/java/org/apache/fop/fo/FOInputHandler.java
index a91ea10d6..5aeb8bf6b 100644
--- a/src/java/org/apache/fop/fo/FOInputHandler.java
+++ b/src/java/org/apache/fop/fo/FOInputHandler.java
@@ -76,9 +76,15 @@ import org.apache.fop.layout.FontInfo;
 import org.xml.sax.SAXException;
 
 /**
- * This class receives structure events from the FO Tree.
- * Sub-classes can then implement various methods to handle
- * the FO Tree when the SAX events occur.
+ * Abstract class defining what should be done with SAX events that map to
+ * XSL-FO input. The events are actually captured by fo/FOTreeBuilder, passed
+ * to the various fo Objects, which in turn, if needed, pass them to an instance
+ * of FOInputHandler.
+ *
+ * Sub-classes will generally fall into one of two categories:
+ * 1) a handler that actually builds an FO Tree from the events, or 2) a
+ * handler that builds a structured (as opposed to formatted) document, such
+ * as our MIF and RTF output targets.
  */
 public abstract class FOInputHandler extends AbstractLogEnabled {
     /**
diff --git a/src/java/org/apache/fop/fo/FOTreeBuilder.java b/src/java/org/apache/fop/fo/FOTreeBuilder.java
index 32dafaecf..bb50b23be 100644
--- a/src/java/org/apache/fop/fo/FOTreeBuilder.java
+++ b/src/java/org/apache/fop/fo/FOTreeBuilder.java
@@ -74,15 +74,20 @@ import java.util.Iterator;
 import java.util.List;
 
 /**
- * SAX Handler that builds the formatting object tree.
- *
- * Modified by Mark Lillywhite mark-fop@inomial.com. Now uses
+ * SAX Handler that passes parsed data to the various
+ * FO objects, where they can be used either to build
+ * an FO Tree, or used by Structure Renderers to build
+ * other data structures.
+ * Now uses
  * StreamRenderer to automagically render the document as
  * soon as it receives a page-sequence end-tag. Also,
  * calls methods to set up and shut down the renderer at
  * the beginning and end of the FO document. Finally,
  * supresses adding the PageSequence object to the Root,
  * since it is parsed immediately.
+ *
+ * @author unascribed
+ * @author Mark Lillywhite mark-fop@inomial.com
  */
 public class FOTreeBuilder extends DefaultHandler {
 
diff --git a/src/java/org/apache/fop/fo/FOTreeHandler.java b/src/java/org/apache/fop/fo/FOTreeHandler.java
index e9d88ceed..b4d8cd464 100644
--- a/src/java/org/apache/fop/fo/FOTreeHandler.java
+++ b/src/java/org/apache/fop/fo/FOTreeHandler.java
@@ -82,9 +82,11 @@ import org.apache.fop.layout.FontInfo;
 import org.apache.fop.render.Renderer;
 
 /**
- * Layout handler that receives the structure events.
+ * Defines how SAX events specific to XSL-FO input should be handled when
+ * an FO Tree needs to be built.
  * This initiates layout processes and corresponding
  * rendering processes such as start/end.
+ * @see FOInputHandler
  */
 public class FOTreeHandler extends FOInputHandler {