cleaned up some of the area tree

removed parent and min/opt/max from area tree, layout managers can handle all this
fixed a number of style errors


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

33 files changed, 913 insertions, 426 deletions

diff --git a/src/org/apache/fop/area/Area.java b/src/org/apache/fop/area/Area.java
index fe9832d1e..5c381d2db 100644
--- a/src/org/apache/fop/area/Area.java
+++ b/src/org/apache/fop/area/Area.java
@@ -105,86 +105,59 @@ public class Area implements Serializable {
 
     private int areaClass = CLASS_NORMAL;
     private int ipd;
+    private HashMap props = null;
 
-    protected Area parent = null; // Doesn't need to be saved in serialization
-
+    /**
+     * Get the area class of this area.
+     *
+     * @return the area class
+     */
     public int getAreaClass() {
         return areaClass;
     }
 
+    /**
+     * Set the area class of this area.
+     *
+     * @param areaClass the area class
+     */
     public void setAreaClass(int areaClass) {
         this.areaClass = areaClass;
     }
 
-    public void setIPD(int i) {
-        ipd = i;
-    }
-
-    public int getIPD() {
-        return ipd;
-    }
-
     /**
-     * Return a length range describing the minimum, optimum and maximum
-     * lengths available for content in the block-progression-direction.
-     * This is calculated from the theoretical maximum size of the area
-     * and its current content.
+     * Set the inline progression dimension of this area.
+     *
+     * @param i the new inline progression dimension
      */
-    public MinOptMax getAvailBPD() {
-        return MinOptMax.subtract(getMaxBPD(), getContentBPD());
+    public void setIPD(int i) {
+        ipd = i;
     }
 
     /**
-     * Return a length range describing the theoretical maximum size of an
-     * area in the block-progression-direction.
-     * For areas holding normal flowing or floating content in paged media,
-     * this depends on the size of the body. In general the answer is the
-     * gotten from the parent. At the body level, the calculation accounts
-     * for the sizes of the conditional areas.
+     * Get the inline progression dimension of this area.
+     *
+     * @return the inline progression dimension
      */
-    public MinOptMax getMaxBPD() {
-        if (parent != null) {
-            return parent.getMaxBPD();
-        } else {
-            return new MinOptMax();
-        }
+    public int getIPD() {
+        return ipd;
     }
 
     /**
-     * Return a length range describing the minimum, optimum and maximum
-     * lengths of all area content in the block-progression-direction.
-     * This is based on the allocation rectangles of all content in
-     * the area.
+     * Add a child to this area.
+     * The default is to do nothing. Subclasses must override
+     * to do something if they can have child areas.
+     *
+     * @param child the child area to add
      */
-    public MinOptMax getContentBPD() {
-        return new MinOptMax();
+    public void addChild(Area child) {
     }
 
     /**
-     * Return a length range describing the minimum, optimum and maximum
-     * lengths of the area's allocation rectangle
-     * in the block-progression-direction.
-     * This is based on the allocation rectangles of all content in
-     * the area.
-     * The default implementation simply returns the same as the content BPD.
-     * If an Area has before or after border and padding, these contribute
-     * to the allocation BPD, depending on conditionality.
+     * Add a trait property to this area.
+     *
+     * @param prop the Trait to add
      */
-    public MinOptMax getAllocationBPD() {
-        return getContentBPD();
-    }
-
-    public void setParent(Area parent) {
-        this.parent = parent;
-    }
-
-    // Do nothing! Let subclasses do something if they can have child areas.
-    public void addChild(Area child) {
-    }
-
-
-    HashMap props = null;
-
     public void addTrait(Trait prop) {
         if (props == null) {
             props = new HashMap(20);
@@ -192,6 +165,12 @@ public class Area implements Serializable {
         props.put(prop.propType, prop.data);
     }
 
+    /**
+     * Add a trait to this area.
+     *
+     * @param traitCode the trait key
+     * @param prop the value of the trait
+     */
     public void addTrait(Object traitCode, Object prop) {
         if (props == null) {
             props = new HashMap(20);
@@ -199,10 +178,21 @@ public class Area implements Serializable {
         props.put(traitCode, prop);
     }
 
+    /**
+     * Get the map of all traits on this area.
+     *
+     * @return the map of traits
+     */
     public HashMap getTraits() {
         return this.props;
     }
 
+    /**
+     * Get a trait from this area.
+     *
+     * @param oTraitCode the trait key
+     * @return the trait value
+     */
     public Object getTrait(Object oTraitCode) {
         return (props != null ? props.get(oTraitCode) : null);
     }
diff --git a/src/org/apache/fop/area/BeforeFloat.java b/src/org/apache/fop/area/BeforeFloat.java
index 643877a6a..18d8f6c79 100644
--- a/src/org/apache/fop/area/BeforeFloat.java
+++ b/src/org/apache/fop/area/BeforeFloat.java
@@ -1,64 +1,54 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.util.List;
-import java.util.ArrayList;
-
+/**
+ * The before float area.
+ * This is used to place the before float areas.
+ * It has an optional separator and before float block children.
+ */
 public class BeforeFloat extends BlockParent {
     // this is an optional block area that will be rendered
     // as the separator only if there are float areas
-    Block separator = null;
-
-    // before float area
-    // has an optional separator
-    // and a list of sub block areas
-
-    ArrayList blocks = null;
-
-    public void addBlock(Block block) {
-        if (blocks == null) {
-            blocks = new ArrayList();
-        }
-        blocks.add(block);
-    }
+    private Block separator = null;
 
+    /**
+     * Set the separator area for this before float.
+     *
+     * @param sep the before float separator area
+     */
     public void setSeparator(Block sep) {
         separator = sep;
     }
 
-    public List getBlocks() {
-        return blocks;
-    }
-
+    /**
+     * Get the separator area for this before float.
+     *
+     * @return the before float separator area
+     */
     public Block getSeparator() {
         return separator;
     }
 
+    /**
+     * Get the height of this before float.
+     * It gets the height of the children and if there is a
+     * separator its height is also added.
+     *
+     * @return the height of the before float including separator
+     */
     public int getHeight() {
-        if (blocks == null) {
-            return 0;
+        int h = super.getHeight();
+        if (separator != null) {
+            h += separator.getHeight();
         }
-        int h = 0;
         return h;
     }
 
-    public MinOptMax getMaxBPD() {
-	MinOptMax maxbpd = parent.getMaxBPD();
-	BodyRegion body = (BodyRegion)parent;
-	Area a =  body.getMainReference();
-	if (a != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	if ((a=body.getFootnote()) != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	return maxbpd;
-    }
-
 }
+
diff --git a/src/org/apache/fop/area/Block.java b/src/org/apache/fop/area/Block.java
index 1c4961d72..655820752 100644
--- a/src/org/apache/fop/area/Block.java
+++ b/src/org/apache/fop/area/Block.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,9 +9,6 @@ package org.apache.fop.area;
 
 import java.io.Serializable;
 import java.util.ArrayList;
-import java.util.List;
-import java.util.Iterator;
-import java.awt.geom.Rectangle2D;
 
 // block areas hold either more block areas or line
 // areas can also be used as a block spacer
@@ -19,10 +16,21 @@ import java.awt.geom.Rectangle2D;
 // or by relative to the parent for floats, tables and lists
 // cacheable object
 // has id information
+
+/**
+ * This is the block area class.
+ * It holds child block areas such as other blocks or lines.
+ */
 public class Block extends BlockParent implements Serializable {
-    // normally stacked with other blocks
+    /**
+     * Normally stacked with other blocks.
+     */
     public static final int STACK = 0;
-    // placed relative to the parent area
+
+    /**
+     * Placed relative to the flow position.
+     * This effects the flow placement of stacking normally.
+     */
     public static final int RELATIVE = 1;
 
     /**
@@ -32,19 +40,16 @@ public class Block extends BlockParent implements Serializable {
     public static final int ABSOLUTE = 2;
 
     private int stacking = TB;
-
-    // list of marker fo objects that are associated with this area
-    // if a retrieve marker resolves this area it will format the
-    // available markers, markers are discarded once page complete
-    private ArrayList markers = null;
+    private int positioning = STACK;
 
     // a block with may contain the dominant styling info in
     // terms of most lines or blocks with info
 
-
-    int positioning = STACK;
-
-
+    /**
+     * Add the block to this block area.
+     *
+     * @param block the block area to add
+     */
     public void addBlock(Block block) {
         if (children == null) {
             children = new ArrayList();
@@ -53,6 +58,11 @@ public class Block extends BlockParent implements Serializable {
         children.add(block);
     }
 
+    /**
+     * Add the line area to this block area.
+     *
+     * @param line the line area to add
+     */
     public void addLineArea(LineArea line) {
         if (children == null) {
             children = new ArrayList();
@@ -61,26 +71,23 @@ public class Block extends BlockParent implements Serializable {
         children.add(line);
     }
 
-    public MinOptMax getContentBPD() {
-        MinOptMax bpd = new MinOptMax();
-        if(children != null) {
-        for(Iterator iter = children.iterator(); iter.hasNext(); ) {
-            Area area = (Area)iter.next();
-            MinOptMax mom = area.getContentBPD();
-            bpd.add(mom);
-        }
-        }
-        return bpd;
-    }
-
+    /**
+     * Set the positioning of this area.
+     *
+     * @param pos the positioning to use when rendering this area
+     */
     public void setPositioning(int pos) {
         positioning = pos;
     }
 
+    /**
+     * Get the positioning of this area.
+     *
+     * @return the positioning to use when rendering this area
+     */
     public int getPositioning() {
         return positioning;
     }
 
-
 }
 
diff --git a/src/org/apache/fop/area/BlockParent.java b/src/org/apache/fop/area/BlockParent.java
index 90f494e27..1604cd86c 100644
--- a/src/org/apache/fop/area/BlockParent.java
+++ b/src/org/apache/fop/area/BlockParent.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -10,7 +10,6 @@ package org.apache.fop.area;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
-import java.awt.geom.Rectangle2D;
 
 /**
  * A BlockParent holds block-level areas.
@@ -20,16 +19,42 @@ public class BlockParent extends Area implements Serializable {
     // this position is used for absolute position
     // or as an indent
     // this has the size in the block progression dimension
+
+    /**
+     * The x offset position of this block parent.
+     * Used for relative and absolute positioning.
+     */
     protected int xOffset = 0;
+
+    /**
+     * The y offset position of this block parent.
+     * Used for relative and absolute positioning.
+     */
     protected int yOffset = 0;
+
+    /**
+     * The width of this block parent.
+     */
     protected int width = 0;
+
+    /**
+     * The height of this block parent.
+     */
     protected int height = 0;
 
-    ArrayList children = null;
+    /**
+     * The children of this block parent area.
+     */
+    protected ArrayList children = null;
 
     // orientation if reference area
-    int orientation = ORIENT_0;
+    private int orientation = ORIENT_0;
 
+    /**
+     * Add the block area to this block parent.
+     *
+     * @param block the child block area to add
+     */
     public void addBlock(Block block) {
         if (children == null) {
             children = new ArrayList();
@@ -37,38 +62,83 @@ public class BlockParent extends Area implements Serializable {
         children.add(block);
     }
 
+    /**
+     * Get the list of child areas for this block area.
+     *
+     * @return the list of child areas
+     */
     public List getChildAreas() {
         return children;
     }
 
+    /**
+     * Set the X offset of this block parent area.
+     *
+     * @param off the x offset of the block parent area
+     */
     public void setXOffset(int off) {
         xOffset = off;
     }
 
+    /**
+     * Set the Y offset of this block parent area.
+     *
+     * @param off the y offset of the block parent area
+     */
     public void setYOffset(int off) {
         yOffset = off;
     }
 
+    /**
+     * Set the width of this block parent area.
+     *
+     * @param w the width of the area
+     */
     public void setWidth(int w) {
         width = w;
     }
 
+    /**
+     * Set the height of this block parent area.
+     *
+     * @param h the height of the block parent area
+     */
     public void setHeight(int h) {
         height = h;
     }
 
+    /**
+     * Get the X offset of this block parent area.
+     *
+     * @return the x offset of the block parent area
+     */
     public int getXOffset() {
         return xOffset;
     }
 
+    /**
+     * Get the Y offset of this block parent area.
+     *
+     * @return the y offset of the block parent area
+     */
     public int getYOffset() {
         return yOffset;
     }
 
+    /**
+     * Get the width of this block parent area.
+     *
+     * @return the width of the area
+     */
     public int getWidth() {
         return width;
     }
 
+    /**
+     * Get the height of this block parent area.
+     *
+     * @return the height of the block parent area
+     */
     public int getHeight() {
         return height;
     }
diff --git a/src/org/apache/fop/area/BlockViewport.java b/src/org/apache/fop/area/BlockViewport.java
index 95443821e..5fcc65896 100644
--- a/src/org/apache/fop/area/BlockViewport.java
+++ b/src/org/apache/fop/area/BlockViewport.java
@@ -1,14 +1,12 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.awt.geom.Rectangle2D;
-
 /**
  * A BlockViewport.
  * This is used for block level Viewport/reference pairs.
@@ -16,26 +14,54 @@ import java.awt.geom.Rectangle2D;
  */
 public class BlockViewport extends Block {
     // clipping for this viewport
-    boolean clip = false;
-    CTM viewportCTM;
+    private boolean clip = false;
+    // transform if rotated or absolute
+    private CTM viewportCTM;
 
+    /**
+     * Create a new block viewport area.
+     */
     public BlockViewport() {
-
     }
 
+    /**
+     * Set the transform of this viewport.
+     * If the viewport is rotated or has an absolute positioning
+     * this transform will do the work.
+     *
+     * @param ctm the transformation
+     */
     public void setCTM(CTM ctm) {
         viewportCTM = ctm;
     }
 
+    /**
+     * Get the transform of this block viewport.
+     *
+     * @return the transformation of this viewport
+     *         or null if normally stacked without rotation
+     */
     public CTM getCTM() {
         return viewportCTM;
     }
 
+    /**
+     * Set the clipping for this viewport.
+     *
+     * @param cl the clipping for the viewport
+     */
     public void setClip(boolean cl) {
         clip = cl;
     }
 
+    /**
+     * Get the clipping for this viewport.
+     *
+     * @return the clipping for the viewport
+     *         true if the contents should be clipped for this viewport
+     */
     public boolean getClip() {
         return clip;
     }
 }
+
diff --git a/src/org/apache/fop/area/BodyRegion.java b/src/org/apache/fop/area/BodyRegion.java
index 5897a27cd..70ceb5f05 100644
--- a/src/org/apache/fop/area/BodyRegion.java
+++ b/src/org/apache/fop/area/BodyRegion.java
@@ -1,67 +1,60 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.awt.geom.Rectangle2D;
-
+/**
+ * The body region area.
+ * This area contains a main reference area and optionally a
+ * before float and footnote area.
+ */
 public class BodyRegion extends RegionReference {
-    BeforeFloat beforeFloat;
-    MainReference mainReference;
-    Footnote footnote;
+    private BeforeFloat beforeFloat;
+    private MainReference mainReference;
+    private Footnote footnote;
     private int columnGap;
     private int columnCount;
 
-    /** Maximum block progression dimension. Note: min=opt=max */
-    private MinOptMax maxBPD;
-
     /** Referenc inline progression dimension for the body. */
     private int refIPD;
 
+    /**
+     * Create a new body region area.
+     * This sets the region reference area class to BODY.
+     */
     public BodyRegion() {
         super(BODY);
     }
 
     // Number of columns when not spanning
     public void setColumnCount(int colCount) {
-	this.columnCount = colCount;
+        this.columnCount = colCount;
     }
 
     // Number of columns when not spanning
     public int getColumnCount() {
-	return this.columnCount ;
+        return this.columnCount;
     }
 
     // A length (mpoints)
     public void setColumnGap(int colGap) {
-	this.columnGap = colGap;
-    }
-
-    public void setParent(Area area) {
-	super.setParent(area);
-	// Only if not scrolling or overflow !!!
-	Rectangle2D refRect = ((RegionViewport)area).getViewArea();
-	maxBPD = new MinOptMax((int)refRect.getHeight());
-	refIPD = (int)refRect.getWidth();
+        this.columnGap = colGap;
     }
 
     public void setBeforeFloat(BeforeFloat bf) {
         beforeFloat = bf;
-	beforeFloat.setParent(this);
     }
 
     public void setMainReference(MainReference mr) {
         mainReference = mr;
-	mainReference.setParent(this);
     }
 
     public void setFootnote(Footnote foot) {
         footnote = foot;
-	footnote.setParent(this);
     }
 
 
@@ -77,10 +70,6 @@ public class BodyRegion extends RegionReference {
         return footnote;
     }
 
-    public MinOptMax getMaxBPD() {
-	return maxBPD;
-    }
-
     public Object clone() {
         BodyRegion br = new BodyRegion();
         br.setCTM(getCTM());
diff --git a/src/org/apache/fop/area/Flow.java b/src/org/apache/fop/area/Flow.java
index 031903b4b..0e8319f21 100644
--- a/src/org/apache/fop/area/Flow.java
+++ b/src/org/apache/fop/area/Flow.java
@@ -1,38 +1,20 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.util.ArrayList;
-import java.util.List;
-
-// this is a normal flow reference area
-// it containts a list of block areas from the flow
+/**
+ * The normal flow reference area class.
+ * This area contains a list of block areas from the flow
+ */
 public class Flow extends BlockParent {
     // the list of blocks created from the flow
-    ArrayList blocks = new ArrayList();
-    int stacking = TB;
-    int width;
-
-    public void addBlock(Block block) {
-        blocks.add(block);
-    }
-
-    public List getBlocks() {
-        return blocks;
-    }
-
-    /**
-     * Maximum block progression dimension for a Flow is
-     * the same as that of its parent Span.
-     */
-    public MinOptMax getMaxBPD() {
-	return parent.getMaxBPD();
-    }
-
+    private int stacking = TB;
+    private int width;
 
 }
+
diff --git a/src/org/apache/fop/area/Footnote.java b/src/org/apache/fop/area/Footnote.java
index cff6fc2fc..7b69e6f28 100644
--- a/src/org/apache/fop/area/Footnote.java
+++ b/src/org/apache/fop/area/Footnote.java
@@ -1,58 +1,45 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.io.Serializable;
-import java.util.List;
-import java.util.ArrayList;
-
 // may combine with before float into a conditional area
+
+/**
+ * Footnote reference area.
+ * This areas holds footnote areas and an optional separator area.
+ */
 public class Footnote extends BlockParent {
-    Block separator = null;
+    private Block separator = null;
 
     // footnote has an optional separator
     // and a list of sub block areas that can be added/removed
 
     // this is the relative position of the footnote inside
     // the body region
-    int top;
-
-    ArrayList blocks = null;
+    private int top;
 
+    /**
+     * Set the separator area for this footnote.
+     *
+     * @param sep the separator area
+     */
     public void setSeparator(Block sep) {
         separator = sep;
     }
 
-    public void addBlock(Block block) {
-        if (blocks == null) {
-            blocks = new ArrayList();
-        }
-        blocks.add(block);
-    }
-
+    /**
+     * Get the separator area for this footnote area.
+     *
+     * @return the separator area
+     */
     public Block getSeparator() {
         return separator;
     }
 
-    public List getBlocks() {
-        return blocks;
-    }
-
-    public MinOptMax getMaxBPD() {
-	MinOptMax maxbpd = parent.getMaxBPD();
-	BodyRegion body = (BodyRegion)parent;
-	Area a =  body.getMainReference();
-	if (a != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	if ((a=body.getBeforeFloat()) != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	return maxbpd;
-    }
 }
+
diff --git a/src/org/apache/fop/area/LineArea.java b/src/org/apache/fop/area/LineArea.java
index 44c8e35d5..e3e99a2f5 100644
--- a/src/org/apache/fop/area/LineArea.java
+++ b/src/org/apache/fop/area/LineArea.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -11,57 +11,92 @@ import org.apache.fop.area.inline.InlineArea;
 
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Iterator;
 
-// a line area can contain information in ranges of child inline
-// areas that have properties such as
-// links, background, underline, bold, id areas
+/**
+ * The line area.
+ * This is a line area that contains inline areas.
+ */
 public class LineArea extends Area {
-    int stacking = LR;
+    private int stacking = LR;
     // contains inline areas
     // has start indent and length, dominant baseline, height
-    int startIndent;
-    int length;
+    private int startIndent;
+    private int length;
 
-    int lineHeight;
+    private int lineHeight;
     // this is the offset for the dominant baseline
-    int baseLine;
+    private int baseLine;
 
     // this class can contain the dominant char styling info
     // this means that many renderers can optimise a bit
 
-    ArrayList inlineAreas = new ArrayList();
+    private ArrayList inlineAreas = new ArrayList();
 
+    /**
+     * Set the height of this line area.
+     *
+     * @param height the height of the line area
+     */
     public void setHeight(int height) {
         lineHeight = height;
     }
 
+    /**
+     * Get the height of this line area.
+     *
+     * @return the height of the line area
+     */
     public int getHeight() {
         return lineHeight;
     }
 
-    public MinOptMax getContentBPD() {
-        return new MinOptMax(lineHeight);
-    }
-
+    /**
+     * Add a child area to this line area.
+     *
+     * @param childArea the inline child area to add
+     */
     public void addChild(Area childArea) {
         if (childArea instanceof InlineArea) {
             addInlineArea((InlineArea)childArea);
         }
     }
 
+    /**
+     * Add an inline child area to this line area.
+     *
+     * @param area the inline child area to add
+     */
     public void addInlineArea(InlineArea area) {
         inlineAreas.add(area);
     }
 
+    /**
+     * Get the inline child areas of this line area.
+     *
+     * @return the list of inline areas
+     */
     public List getInlineAreas() {
         return inlineAreas;
     }
 
+    /**
+     * Set the start indent of this line area.
+     * The start indent is used for offsetting the start of
+     * the inline areas for alignment or other indents.
+     *
+     * @param si the start indent value
+     */
     public void setStartIndent(int si) {
         startIndent = si;
     }
 
+    /**
+     * Get the start indent of this line area.
+     * The start indent is used for offsetting the start of
+     * the inline areas for alignment or other indents.
+     *
+     * @return the start indent value
+     */
     public int getStartIndent() {
         return startIndent;
     }
diff --git a/src/org/apache/fop/area/LineTrait.java b/src/org/apache/fop/area/LineTrait.java
index e02725c28..3341d8d4d 100644
--- a/src/org/apache/fop/area/LineTrait.java
+++ b/src/org/apache/fop/area/LineTrait.java
@@ -1,13 +1,17 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
+/**
+ * Traits for a range of areas in a line.
+ * Not sure if this is needed.
+ */
 public class LineTrait extends Trait {
-    int[] range;
+    private int[] range;
 }
 
diff --git a/src/org/apache/fop/area/MainReference.java b/src/org/apache/fop/area/MainReference.java
index b18401995..b38e20179 100644
--- a/src/org/apache/fop/area/MainReference.java
+++ b/src/org/apache/fop/area/MainReference.java
@@ -1,49 +1,59 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
-import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
 
-// the area that contains the flow via the span areas
-public class MainReference extends Area implements Serializable {
-    List spanAreas = new ArrayList();
-    int columnGap;
-    int width;
-
+/**
+ * The main body reference area.
+ * This area that contains the flow via the span areas.
+ */
+public class MainReference extends Area {
+    private List spanAreas = new ArrayList();
+    private int columnGap;
+    private int width;
+
+    /**
+     * Add a span area to this area.
+     *
+     * @param span the span area to add
+     */
     public void addSpan(Span span) {
         spanAreas.add(span);
-	span.setParent(this);
     }
 
+    /**
+     * Get the span areas from this area.
+     *
+     * @return the list of span areas
+     */
     public List getSpans() {
         return spanAreas;
     }
 
+    /**
+     * Get the column gap in millipoints.
+     *
+     * @return the column gap in millioints
+     */
     public int getColumnGap() {
         return columnGap;
     }
 
+    /**
+     * Get the width of this reference area.
+     *
+     * @return the width
+     */
     public int getWidth() {
         return width;
     }
 
-    public MinOptMax getMaxBPD() {
-	MinOptMax maxbpd = parent.getMaxBPD();
-	BodyRegion body = (BodyRegion)parent;
-	Area a =  body.getBeforeFloat();
-	if (a != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	if ((a=body.getFootnote()) != null) {
-	    maxbpd = MinOptMax.subtract(maxbpd, a.getContentBPD());
-	}
-	return maxbpd;
-    }
 }
+
diff --git a/src/org/apache/fop/area/MinOptMax.java b/src/org/apache/fop/area/MinOptMax.java
index 545b9b06e..3c68fafb0 100644
--- a/src/org/apache/fop/area/MinOptMax.java
+++ b/src/org/apache/fop/area/MinOptMax.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -13,7 +13,6 @@ package org.apache.fop.area;
  * MinOptMax values are used during layout calculations. The instance
  * variables are package visible.
  */
-
 public class MinOptMax implements java.io.Serializable, Cloneable {
 
     /** Publicly visible min(imum), opt(imum) and max(imum) values.*/
@@ -22,55 +21,54 @@ public class MinOptMax implements java.io.Serializable, Cloneable {
     public int max;
 
     public MinOptMax() {
-	this(0);
+        this(0);
     }
 
     public MinOptMax(int val) {
-	this(val, val, val);
+        this(val, val, val);
     }
 
     public MinOptMax(int min, int opt, int max) {
-	this.min = min;
-	this.opt = opt;
-	this.max = max;
+        this.min = min;
+        this.opt = opt;
+        this.max = max;
     }
 
     public Object clone() {
-	try {
-	    return super.clone();
-	} catch (CloneNotSupportedException ex) {
-	    // SHOULD NEVER OCCUR - all members are primitive types!
-	    return null;
-	}
+        try {
+            return super.clone();
+        } catch (CloneNotSupportedException ex) {
+            // SHOULD NEVER OCCUR - all members are primitive types!
+            return null;
+        }
     }
 
     public static MinOptMax subtract(MinOptMax op1, MinOptMax op2) {
-	return new MinOptMax(op1.min - op2.max, op1.opt - op2.opt,
-			     op1.max - op2.min);
+        return new MinOptMax(op1.min - op2.max, op1.opt - op2.opt,
+                             op1.max - op2.min);
     }
 
     public static MinOptMax add(MinOptMax op1, MinOptMax op2) {
-	return new MinOptMax(op1.min + op2.min, op1.opt + op2.opt,
-			     op1.max + op2.max);
+        return new MinOptMax(op1.min + op2.min, op1.opt + op2.opt,
+                             op1.max + op2.max);
     }
 
     public static MinOptMax multiply(MinOptMax op1, double mult) {
-	return new MinOptMax((int)(op1.min * mult),
-			     (int)(op1.opt * mult),
-			     (int)(op1.max * mult));
+        return new MinOptMax((int)(op1.min * mult),
+                             (int)(op1.opt * mult), (int)(op1.max * mult));
     }
 
     public void add(MinOptMax op) {
-	min += op.min;
-	opt += op.opt;
-	max += op.max;
+        min += op.min;
+        opt += op.opt;
+        max += op.max;
     }
 
     public void subtract(MinOptMax op) {
-	min -= op.max;
-	opt -= op.opt;
-	max -= op.min;
+        min -= op.max;
+        opt -= op.opt;
+        max -= op.min;
     }
 
-
 }
+
diff --git a/src/org/apache/fop/area/Page.java b/src/org/apache/fop/area/Page.java
index 41b72f8c2..cae3873b8 100644
--- a/src/org/apache/fop/area/Page.java
+++ b/src/org/apache/fop/area/Page.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -23,19 +23,26 @@ import java.util.HashMap;
  */
 public class Page implements Serializable, Cloneable {
     // contains before, start, body, end and after regions
-    RegionViewport regionBefore = null;
-    RegionViewport regionStart = null;
-    RegionViewport regionBody = null;
-    RegionViewport regionEnd = null;
-    RegionViewport regionAfter = null;
+    private RegionViewport regionBefore = null;
+    private RegionViewport regionStart = null;
+    private RegionViewport regionBody = null;
+    private RegionViewport regionEnd = null;
+    private RegionViewport regionAfter = null;
 
     // hashmap of markers for this page
     // start and end are added by the fo that contains the markers
-    HashMap markerStart = null;
-    HashMap markerEnd = null;
+    private HashMap markerStart = null;
+    private HashMap markerEnd = null;
 
+    // temporary map of unresolved objects used when serializing the page
     private HashMap unresolved = null;
 
+    /**
+     * Set the region on this page.
+     *
+     * @param areaclass the area class of the region to set
+     * @param port the region viewport to set
+     */
     public void setRegion(int areaclass, RegionViewport port) {
         if (areaclass == RegionReference.BEFORE) {
             regionBefore = port;
@@ -50,6 +57,12 @@ public class Page implements Serializable, Cloneable {
         }
     }
 
+    /**
+     * Get the region from this page.
+     *
+     * @param areaclass the region area class
+     * @return the region viewport or null if none
+     */
     public RegionViewport getRegion(int areaclass) {
         if (areaclass == RegionReference.BEFORE) {
             return regionBefore;
@@ -65,26 +78,49 @@ public class Page implements Serializable, Cloneable {
         return null;
     }
 
+    /**
+     * Clone this page.
+     * This returns a new page with a clone of all the regions.
+     *
+     * @return a new clone of this page
+     */
     public Object clone() {
         Page p = new Page();
-        if(regionBefore != null)
+        if (regionBefore != null) {
             p.regionBefore = (RegionViewport)regionBefore.clone();
-        if(regionStart != null)
+        }
+        if (regionStart != null) {
             p.regionStart = (RegionViewport)regionStart.clone();
-        if(regionBody != null)
+        }
+        if (regionBody != null) {
             p.regionBody = (RegionViewport)regionBody.clone();
-        if(regionEnd != null)
+        }
+        if (regionEnd != null) {
             p.regionEnd = (RegionViewport)regionEnd.clone();
-        if(regionAfter != null)
+        }
+        if (regionAfter != null) {
             p.regionAfter = (RegionViewport)regionAfter.clone();
+        }
 
         return p;
     }
 
+    /**
+     * Set the unresolved references on this page for serializing.
+     *
+     * @param unres the map of unresolved objects
+     */
     public void setUnresolvedReferences(HashMap unres) {
         unresolved = unres;
     }
-    
+
+    /**
+     * Get the map unresolved references from this page.
+     * This should be called after deserializing to retrieve
+     * the map of unresolved references that were serialized.
+     *
+     * @return the de-serialized map of unresolved objects
+     */
     public HashMap getUnresolvedReferences() {
         return unresolved;
     }
diff --git a/src/org/apache/fop/area/RegionReference.java b/src/org/apache/fop/area/RegionReference.java
index 2a4519658..30a621760 100644
--- a/src/org/apache/fop/area/RegionReference.java
+++ b/src/org/apache/fop/area/RegionReference.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -11,15 +11,47 @@ import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * This is a region reference area for the page regions.
+ * This area represents a region on the page. It is cloneable
+ * so the page master can make copies from the original page and regions.
+ */
 public class RegionReference extends Area implements Serializable, Cloneable {
+    /**
+     * The before region.
+     */
     public static final int BEFORE = 0;
+
+    /**
+     * The start region.
+     */
     public static final int START = 1;
+    
+    /**
+     * The body region.
+     */
     public static final int BODY = 2;
+    
+    /**
+     * The end region.
+     */
     public static final int END = 3;
+    
+    /**
+     * The after region.
+     */
     public static final int AFTER = 4;
-    int regionClass = BEFORE;
+
+    private int regionClass = BEFORE;
     private CTM ctm;
+    // the list of block areas from the static flow
+    private ArrayList blocks = new ArrayList();
 
+    /**
+     * Create a new region reference area.
+     *
+     * @param type the region class type
+     */
     public RegionReference(int type) {
         regionClass = type;
     }
@@ -30,30 +62,56 @@ public class RegionReference extends Area implements Serializable, Cloneable {
      * terms of "start" and "before" into coordinates in a system which
      * is positioned in "absolute" directions (with origin at lower left of
      * the region reference area.
+     *
+     * @param ctm the current transform to position this region
      */
     public void setCTM(CTM ctm) {
         this.ctm = ctm;
     }
 
+    /**
+     * Get the current transform of this region.
+     *
+     * @return ctm the current transform to position this region
+     */
     public CTM getCTM() {
         return this.ctm;
     }
 
-    // the list of block areas from the static flow
-    ArrayList blocks = new ArrayList();
-
+    /**
+     * Get the block in this region.
+     *
+     * @return the list of blocks in this region
+     */
     public List getBlocks() {
         return blocks;
     }
 
+    /**
+     * Get the region class of this region.
+     *
+     * @return the region class
+     */
     public int getRegionClass() {
         return regionClass;
     }
 
+    /**
+     * Add a block area to this region reference area.
+     *
+     * @param block the block area to add
+     */
     public void addBlock(Block block) {
         blocks.add(block);
     }
 
+    /**
+     * Clone this region.
+     * This is used when cloning the page by the page master.
+     * The blocks are not copied since the master will have no blocks.
+     *
+     * @return a copy of this region reference area
+     */
     public Object clone() {
         RegionReference rr = new RegionReference(regionClass);
         rr.ctm = ctm;
diff --git a/src/org/apache/fop/area/RegionViewport.java b/src/org/apache/fop/area/RegionViewport.java
index 85c8bf8a3..0886b17fe 100644
--- a/src/org/apache/fop/area/RegionViewport.java
+++ b/src/org/apache/fop/area/RegionViewport.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -8,33 +8,59 @@
 package org.apache.fop.area;
 
 import java.awt.geom.Rectangle2D;
-import java.io.Serializable;
 import java.io.IOException;
 
-public class RegionViewport extends Area implements Serializable, Cloneable {
+/**
+ * Region Viewport reference area.
+ * This area is the viewport for a region and contains a region area.
+ */
+public class RegionViewport extends Area implements Cloneable {
     // this rectangle is relative to the page
-    RegionReference region;
-    Rectangle2D viewArea;
-    boolean clip = false;
-
+    private RegionReference region;
+    private Rectangle2D viewArea;
+    private boolean clip = false;
 
+    /**
+     * Create a new region viewport.
+     *
+     * @param viewArea the view area of this viewport
+     */
     public RegionViewport(Rectangle2D viewArea) {
         this.viewArea = viewArea;
     }
 
+    /**
+     * Set the region for this region viewport.
+     *
+     * @param reg the child region inside this viewport
+     */
     public void setRegion(RegionReference reg) {
         region = reg;
-	region.setParent(this);
     }
 
+    /**
+     * Get the region for this region viewport.
+     *
+     * @return the child region inside this viewport
+     */
     public RegionReference getRegion() {
         return region;
     }
 
+    /**
+     * Set the clipping for this region viewport.
+     *
+     * @param c the clipping value
+     */
     public void setClip(boolean c) {
         clip = c;
     }
 
+    /**
+     * Get the view area of this viewport.
+     *
+     * @return the viewport rectangle area
+     */
     public Rectangle2D getViewArea() {
         return viewArea;
     }
@@ -52,15 +78,20 @@ public class RegionViewport extends Area implements Serializable, Cloneable {
     private void readObject(java.io.ObjectInputStream in)
     throws IOException, ClassNotFoundException {
         viewArea = new Rectangle2D.Float(in.readFloat(), in.readFloat(),
-					 in.readFloat(), in.readFloat());
+                                         in.readFloat(), in.readFloat());
         clip = in.readBoolean();
-        setRegion( (RegionReference) in.readObject());
+        setRegion((RegionReference) in.readObject());
     }
 
+    /**
+     * Clone this region viewport.
+     * Used when creating a copy from the page master.
+     *
+     * @return a new copy of this region viewport
+     */
     public Object clone() {
         RegionViewport rv = new RegionViewport((Rectangle2D)viewArea.clone());
         rv.region = (RegionReference)region.clone();
-        rv.region.setParent(rv);
         return rv;
     }
 }
diff --git a/src/org/apache/fop/area/Resolveable.java b/src/org/apache/fop/area/Resolveable.java
index edfcce6b8..3085a8130 100644
--- a/src/org/apache/fop/area/Resolveable.java
+++ b/src/org/apache/fop/area/Resolveable.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -16,9 +16,22 @@ import java.util.List;
  */
 public interface Resolveable {
 
-    public boolean isResolved();
+    /**
+     * Check if this area has been resolved.
+     *
+     * @return true once this area is resolved
+     */
+    boolean isResolved();
 
-    public String[] getIDs();
+    /**
+     * Get the array of id references of this resolveable object.
+     * If this object contains child resolveables that are
+     * resolved through this then it should return the id's of
+     * the child also.
+     *
+     * @return the id references for resolving this object
+     */
+    String[] getIDs();
 
     /**
      * This resolves reference with a list of pages.
@@ -27,5 +40,5 @@ public interface Resolveable {
      * @param pages the list of pages with the id area
      *              may be null if not found
      */
-    public void resolve(String id, List pages);
+    void resolve(String id, List pages);
 }
diff --git a/src/org/apache/fop/area/Span.java b/src/org/apache/fop/area/Span.java
index 20661dad7..0f563d481 100644
--- a/src/org/apache/fop/area/Span.java
+++ b/src/org/apache/fop/area/Span.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -8,13 +8,12 @@
 package org.apache.fop.area;
 
 import java.util.ArrayList;
-import java.util.Iterator;
 
 // this is a reference area block area with 0 border and padding
 public class Span extends Area {
     // the list of flow reference areas in this span area
-    ArrayList flowAreas;
-    int height;
+    private ArrayList flowAreas;
+    private int height;
 
     public Span(int cols) {
         flowAreas = new ArrayList(cols);
@@ -22,7 +21,6 @@ public class Span extends Area {
 
     public void addFlow(Flow flow) {
         flowAreas.add(flow);
-	flow.setParent(this);
     }
 
     public int getColumnCount() {
@@ -37,20 +35,5 @@ public class Span extends Area {
         return (Flow) flowAreas.get(count);
     }
 
-    /**
-     * Maximum available BPD for a Span is the maxBPD for its containing
-     * MainReference less the content BPD of any previous spans
-     */
-    public MinOptMax getMaxBPD() {
-	MinOptMax maxbpd = parent.getMaxBPD();
-	MainReference mainref = (MainReference)parent;
-	Iterator spanIter = mainref.getSpans().iterator();
-	while (spanIter.hasNext()) {
-	    Span s = (Span)spanIter.next();
-	    if (s == this) break;
-	    maxbpd = MinOptMax.subtract(maxbpd, s.getContentBPD());
-	}
-	return maxbpd;
-    }
-
 }
+
diff --git a/src/org/apache/fop/area/Title.java b/src/org/apache/fop/area/Title.java
index 26cf7db61..7dba2f535 100644
--- a/src/org/apache/fop/area/Title.java
+++ b/src/org/apache/fop/area/Title.java
@@ -1,11 +1,16 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area;
 
+/**
+ * The title area.
+ * This area holds the inline areas from the page-sequence
+ * title element.
+ */
 public class Title extends LineArea {
 }
diff --git a/src/org/apache/fop/area/Trait.java b/src/org/apache/fop/area/Trait.java
index 8d2f06e29..e63e33cf0 100644
--- a/src/org/apache/fop/area/Trait.java
+++ b/src/org/apache/fop/area/Trait.java
@@ -17,20 +17,81 @@ import java.util.HashMap;
 import java.util.Iterator;
 
 // properties should be serialized by the holder
+/**
+ * Area traits used for rendering.
+ * This class represents an area trait that specifies a value for rendering.
+ */
 public class Trait implements Serializable {
+    /**
+     * Id reference line, not resolved.
+     * not sure if this is needed.
+     */
     public static final Integer ID_LINK = new Integer(0);
+
+    /**
+     * Internal link trait.
+     * This is resolved and provides a link to an internal area.
+     */
     public static final Integer INTERNAL_LINK = new Integer(1); //resolved
+
+    /**
+     * External link. A URL link to an external resource.
+     */
     public static final Integer EXTERNAL_LINK = new Integer(2);
+
+    /**
+     * The font name from the font setup.
+     */
     public static final Integer FONT_NAME = new Integer(3);
+
+    /**
+     * Font size for the current font.
+     */
     public static final Integer FONT_SIZE = new Integer(4);
+
+    /**
+     * The current colour.
+     */
     public static final Integer COLOR = new Integer(7);
+
+    /**
+     * Don't think this is necessary.
+     */
     public static final Integer ID_AREA = new Integer(8);
+
+    /**
+     * Background trait for an area.
+     */
     public static final Integer BACKGROUND = new Integer(9);
+
+    /**
+     * Underline trait used when rendering inline parent.
+     */
     public static final Integer UNDERLINE = new Integer(10);
+
+    /**
+     * Overline trait used when rendering inline parent.
+     */
     public static final Integer OVERLINE = new Integer(11);
+
+    /**
+     * Linethrough trait used when rendering inline parent.
+     */
     public static final Integer LINETHROUGH = new Integer(12);
+
+    /**
+     *
+     */
     public static final Integer OFFSET = new Integer(13);
+
+    /**
+     * The shadow for text.
+     */
     public static final Integer SHADOW = new Integer(14);
+
+    /**
+     * The border start.
+     */
     public static final Integer BORDER_START = new Integer(15);
     public static final Integer BORDER_END = new Integer(16);
     public static final Integer BORDER_BEFORE = new Integer(17);
diff --git a/src/org/apache/fop/area/TreeExt.java b/src/org/apache/fop/area/TreeExt.java
index cf4698918..8cca59cfd 100644
--- a/src/org/apache/fop/area/TreeExt.java
+++ b/src/org/apache/fop/area/TreeExt.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -8,13 +8,53 @@
 package org.apache.fop.area;
 
 /**
+ * Area tree extension interface.
+ * This interface is used by area tree extensions that are handled
+ * by the renderer.
+ * When this extension is handled by the area tree it is rendered
+ * according to the three possibilities, IMMEDIATELY, AFTER_PAGE
+ * or END_OF_DOC.
  */
 public interface TreeExt {
-    public final static int IMMEDIATELY = 0;
-    public final static int AFTER_PAGE = 1;
-    public final static int END_OF_DOC = 2;
+    /**
+     * Render this extension immediately when
+     * being handled by the area tree.
+     */
+    public static final int IMMEDIATELY = 0;
 
-    public boolean isResolveable();
-    public String getMimeType();
-    public String getName();
+    /**
+     * Render this extension after the next page is rendered
+     * or prepared when being handled by the area tree.
+     */
+    public static final int AFTER_PAGE = 1;
+
+    /**
+     * Render this extension at the end of the document once
+     * all pages have been fully rendered.
+     */
+    public static final int END_OF_DOC = 2;
+
+    /**
+     * Check if this tree extension is also resolveable so that
+     * the area tree can do id reference resolution when the
+     * extension is added to the area tree.
+     *
+     * @return true if this also implements resolveable
+     */
+    boolean isResolveable();
+
+    /**
+     * Get the mime type for the document that this area tree
+     * extension applies.
+     *
+     * @return the mime type of the document where this applies
+     */
+    String getMimeType();
+
+    /**
+     * Get the name of this extension.
+     *
+     * @return the name of this extension
+     */
+    String getName();
 }
diff --git a/src/org/apache/fop/area/inline/Anchor.java b/src/org/apache/fop/area/inline/Anchor.java
index 128d5231b..ea3026b2a 100644
--- a/src/org/apache/fop/area/inline/Anchor.java
+++ b/src/org/apache/fop/area/inline/Anchor.java
@@ -1,12 +1,16 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area.inline;
 
+/**
+ * Anchor area for footnote or float.
+ * Not sure if this is needed.
+ */
 public class Anchor extends InlineArea {
 
     // has a keep with adjacent area
diff --git a/src/org/apache/fop/area/inline/Character.java b/src/org/apache/fop/area/inline/Character.java
index 3b19ef5d7..a7e5f2aa3 100644
--- a/src/org/apache/fop/area/inline/Character.java
+++ b/src/org/apache/fop/area/inline/Character.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,18 +9,38 @@ package org.apache.fop.area.inline;
 
 import org.apache.fop.render.Renderer;
 
+/**
+ * Single character inline area.
+ * This inline area holds a single characater.
+ */
 public class Character extends InlineArea {
-    char character;
+    private char character;
+
+    /**
+     * Create a new characater inline area with the given character.
+     *
+     * @param ch the character for this inline area
+     */
     public Character(char ch) {
         character = ch;
     }
 
     // character info: font, char spacing, colour, baseline
 
+    /**
+     * Render this inline area.
+     *
+     * @param renderer the renderer to render this character area
+     */
     public void render(Renderer renderer) {
         renderer.renderCharacter(this);
     }
 
+    /**
+     * Get the character for this inline character area.
+     *
+     * @return the character
+     */
     public char getChar() {
         return character;
     }
diff --git a/src/org/apache/fop/area/inline/FilledArea.java b/src/org/apache/fop/area/inline/FilledArea.java
index b92c3e997..38ce5d9b4 100644
--- a/src/org/apache/fop/area/inline/FilledArea.java
+++ b/src/org/apache/fop/area/inline/FilledArea.java
@@ -1,14 +1,12 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.area.inline;
 
-import org.apache.fop.area.MinOptMax;
-
 import java.util.List;
 import java.util.ArrayList;
 
@@ -18,17 +16,35 @@ import java.util.ArrayList;
  * When the renderer gets the child areas to render
  * the inline areas are repeated to fill the ipd of
  * this inline parent.
+ * This extends InlineParent so that the renderer will render
+ * this as a normal inline parent.
  */
 public class FilledArea extends InlineParent {
     private int unitWidth;
 
+    /**
+     * Create a new filled area.
+     */
     public FilledArea() {
     }
 
+    /**
+     * Set the unit width for the areas to fill the full width.
+     *
+     * @param w the unit width
+     */
     public void setUnitWidth(int w) {
         unitWidth = w;
     }
 
+    /**
+     * Get the child areas for this filed area.
+     * This copies the references of the inline areas so that
+     * it fills the total width of the area a whole number of times
+     * for the unit width.
+     *
+     * @return the list of child areas copied to fill the width
+     */
     public List getChildAreas() {
         int units = (int)(getWidth() / unitWidth);
         ArrayList newList = new ArrayList();
diff --git a/src/org/apache/fop/area/inline/ForeignObject.java b/src/org/apache/fop/area/inline/ForeignObject.java
index 54f35f73c..f28175b7a 100644
--- a/src/org/apache/fop/area/inline/ForeignObject.java
+++ b/src/org/apache/fop/area/inline/ForeignObject.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -12,22 +12,42 @@ import org.apache.fop.area.Area;
 import org.w3c.dom.Document;
 
 // cacheable object
+/**
+ * Foreign object inline area.
+ * This inline area represents an instream-foreign object.
+ * This holds an xml document and the associated namespace.
+ */
 public class ForeignObject extends Area {
-    Document doc;
-    String namespace;
-    // dom object
-    // height, width
+    private Document doc;
+    private String namespace;
 
+    /**
+     * Create a new foreign object with the given dom and namespace.
+     *
+     * @param d the xml document
+     * @param ns the namespace of the document
+     */
     public ForeignObject(Document d, String ns) {
         doc = d;
         namespace = ns;
     }
 
+    /**
+     * Get the document for this foreign object.
+     *
+     * @return the xml document
+     */
     public Document getDocument() {
         return doc;
     }
 
+    /**
+     * Get the namespace of this foreign object.
+     *
+     * @return the namespace of this document
+     */
     public String getNameSpace() {
         return namespace;
     }
 }
+
diff --git a/src/org/apache/fop/area/inline/Image.java b/src/org/apache/fop/area/inline/Image.java
index 47574369b..7705227d6 100644
--- a/src/org/apache/fop/area/inline/Image.java
+++ b/src/org/apache/fop/area/inline/Image.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,17 +9,29 @@ package org.apache.fop.area.inline;
 
 import org.apache.fop.area.Area;
 
-// cacheable object
-// image object, mime type, url
-// an image only needs to be loaded to get the size if not specified
-// and when rendering to the output
+/**
+ * Image area for external-graphic.
+ * This area holds information for rendering an image.
+ * The url of the image is used as a key to reference the image cache.
+ */
 public class Image extends Area {
-    String url;
+    private String url;
 
+    /**
+     * Create a new image with the given url.
+     *
+     * @param u the url of the image
+     */
     public Image(String u) {
         url = u;
     }
 
+    /**
+     * Get the url of this image.
+     * This url is used as a key to locate the actual image data.
+     *
+     * @return the url of this image
+     */
     public String getURL() {
         return url;
     }
diff --git a/src/org/apache/fop/area/inline/InlineArea.java b/src/org/apache/fop/area/inline/InlineArea.java
index 58cd68871..701f98c09 100644
--- a/src/org/apache/fop/area/inline/InlineArea.java
+++ b/src/org/apache/fop/area/inline/InlineArea.java
@@ -8,11 +8,9 @@
 package org.apache.fop.area.inline;
 
 import org.apache.fop.area.Area;
-import org.apache.fop.area.MinOptMax;
 import org.apache.fop.area.Trait;
 import org.apache.fop.render.Renderer;
 import org.apache.fop.traits.BorderProps;
-import org.apache.fop.fo.properties.VerticalAlign;
 
 import java.util.ArrayList;
 
@@ -25,19 +23,24 @@ import java.util.ArrayList;
  */
 public class InlineArea extends Area {
     // int width;
-    int height;
+    private int height;
     protected int contentIPD = 0;
 
     // offset position from top of parent area
     int verticalPosition = 0;
 
     // store properties in array list, need better solution
-    ArrayList props = null;
-
-    // inline areas are expected to implement this method
-    // to render themselves
+    private ArrayList props = null;
+
+    /**
+     * Render this inline area.
+     * Inline areas that extend this class are expected
+     * to implement this method to render themselves in
+     * the renderer.
+     *
+     * @param renderer the renderer to render this inline area
+     */
     public void render(Renderer renderer) {
-
     }
 
     public void setWidth(int w) {
@@ -87,10 +90,6 @@ public class InlineArea extends Area {
         return iBP;
     }
 
-    public MinOptMax getAllocationIPD() {
-        return new MinOptMax(getAllocIPD());
-    }
-
     public void setOffset(int v) {
         verticalPosition = v;
     }
diff --git a/src/org/apache/fop/area/inline/InlineParent.java b/src/org/apache/fop/area/inline/InlineParent.java
index d1f66124a..33216bf81 100644
--- a/src/org/apache/fop/area/inline/InlineParent.java
+++ b/src/org/apache/fop/area/inline/InlineParent.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -19,13 +19,20 @@ import java.util.ArrayList;
  * This is an inline area that can have other inlines as children.
  */
 public class InlineParent extends InlineArea {
+    /**
+     * The list of inline areas added to this inline parent.
+     */
     protected ArrayList inlines = new ArrayList();
 
+    /**
+     * Create a new inline parent to add areas to.
+     */
     public InlineParent() {
     }
 
     /**
      * Render this area.
+     *
      * @param renderer the renderer to render this area in
      */
     public void render(Renderer renderer) {
@@ -34,14 +41,21 @@ public class InlineParent extends InlineArea {
 
     /**
      * Override generic Area method.
+     *
+     * @param childArea the child area to add
      */
     public void addChild(Area childArea) {
-	if (childArea instanceof InlineArea) {
-	    inlines.add(childArea);
-	    increaseIPD( ((InlineArea)childArea).getAllocIPD());
-	}
+        if (childArea instanceof InlineArea) {
+            inlines.add(childArea);
+            increaseIPD(((InlineArea) childArea).getAllocIPD());
+        }
     }
 
+    /**
+     * Get the child areas for this inline parent.
+     *
+     * @return the list of child areas
+     */
     public List getChildAreas() {
         return inlines;
     }
diff --git a/src/org/apache/fop/area/inline/Leader.java b/src/org/apache/fop/area/inline/Leader.java
index 0bc5415a5..587c02c25 100644
--- a/src/org/apache/fop/area/inline/Leader.java
+++ b/src/org/apache/fop/area/inline/Leader.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -10,7 +10,11 @@ package org.apache.fop.area.inline;
 import org.apache.fop.render.Renderer;
 import org.apache.fop.fo.properties.RuleStyle;
 
-public class Leader extends Stretch {
+/**
+ * This is a leader inline area.
+ * This class is only used for leader with leader-pattern of rule.
+ */
+public class Leader extends InlineArea {
 
     // pattern, length min opt max
 
@@ -19,29 +23,56 @@ public class Leader extends Stretch {
     // if space replaced with a space
     // otherwise this is a holder for a line
 
-    int ruleStyle = RuleStyle.SOLID;
-    int ruleThickness = 1000;
+    private int ruleStyle = RuleStyle.SOLID;
+    private int ruleThickness = 1000;
 
+    /**
+     * Create a new leader area.
+     */
     public Leader() {
-
     }
 
+    /**
+     * Set the rule style of this leader area.
+     *
+     * @param style the rule style for the leader line
+     */
     public void setRuleStyle(int style) {
         ruleStyle = style;
     }
 
+    /**
+     * Set the rule thickness of the rule in miilipoints.
+     *
+     * @param rt the rule thickness in millipoints
+     */
     public void setRuleThickness(int rt) {
         ruleThickness = rt;
     }
 
+    /**
+     * Get the rule style of this leader.
+     *
+     * @return the rule style
+     */
     public int getRuleStyle() {
         return ruleStyle;
     }
 
+    /**
+     * Get the rule thickness of the rule in miilipoints.
+     *
+     * @return the rule thickness in millipoints
+     */
     public int getRuleThickness() {
         return ruleThickness;
     }
 
+    /**
+     * Render this leader in the current renderer.
+     *
+     * @param renderer the renderer to render this inline area
+     */
     public void render(Renderer renderer) {
         renderer.renderLeader(this);
     }
diff --git a/src/org/apache/fop/area/inline/Space.java b/src/org/apache/fop/area/inline/Space.java
index 7b98b3c17..249743ad3 100644
--- a/src/org/apache/fop/area/inline/Space.java
+++ b/src/org/apache/fop/area/inline/Space.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,8 +9,17 @@ package org.apache.fop.area.inline;
 
 import org.apache.fop.render.Renderer;
 
-public class Space extends Stretch {
+/**
+ * Inline space area.
+ * This is used for adding a inline space to the output.
+ */
+public class Space extends InlineArea {
 
+    /**
+     * Render this inlien space area.
+     *
+     * @param renderer the renderer to render this inline area
+     */
     public void render(Renderer renderer) {
         renderer.renderInlineSpace(this);
     }
diff --git a/src/org/apache/fop/area/inline/Stretch.java b/src/org/apache/fop/area/inline/Stretch.java
deleted file mode 100644
index fd173e850..000000000
--- a/src/org/apache/fop/area/inline/Stretch.java
+++ /dev/null
@@ -1,27 +0,0 @@
-/*
- * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
- * For details on use and redistribution please refer to the
- * LICENSE file included with these sources.
- */
-
-package org.apache.fop.area.inline;
-
-import org.apache.fop.area.MinOptMax;
-
-public class Stretch extends InlineArea {
-    MinOptMax contentIPD = null;
-
-    public void setAllocationIPD(MinOptMax mom) {
-        contentIPD = mom;
-    }
-
-    public MinOptMax getAllocationIPD() {
-        // Should also account for any borders and padding in the
-        // inline progression dimension
-        if (contentIPD != null) {
-            return contentIPD;
-        }
-        return super.getAllocationIPD();
-    }
-}
diff --git a/src/org/apache/fop/area/inline/UnresolvedPageNumber.java b/src/org/apache/fop/area/inline/UnresolvedPageNumber.java
index 952949506..4a8246dba 100644
--- a/src/org/apache/fop/area/inline/UnresolvedPageNumber.java
+++ b/src/org/apache/fop/area/inline/UnresolvedPageNumber.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -13,22 +13,47 @@ import org.apache.fop.area.Trait;
 
 import java.util.List;
 
+/**
+ * Unresolveable page number area.
+ * This is a word area that resolves itself to a page number
+ * from an id reference.
+ */
 public class UnresolvedPageNumber extends Word implements Resolveable {
     private boolean resolved = false;
     private String pageRefId;
 
+    /**
+     * Create a new unresolveable page number.
+     *
+     * @param id the id reference for resolving this
+     */
     public UnresolvedPageNumber(String id) {
         pageRefId = id;
         word = "?";
     }
 
+    /**
+     * Get the id references for this area.
+     *
+     * @return the id reference for this unresolved page number
+     */
     public String[] getIDs() {
         return new String[] {pageRefId};
     }
 
+    /**
+     * Resolve this page number reference.
+     * This resolves the reference by getting the page number
+     * string from the first page in the list of pages that apply
+     * for the id reference. The word string is then set to the
+     * page number string.
+     *
+     * @param id the id reference being resolved
+     * @param pages the list of pages for the id reference
+     */
     public void resolve(String id, List pages) {
         resolved = true;
-        if(pages != null) {
+        if (pages != null) {
             PageViewport page = (PageViewport)pages.get(0);
             String str = page.getPageNumber();
             word = str;
@@ -41,6 +66,11 @@ public class UnresolvedPageNumber extends Word implements Resolveable {
         }
     }
 
+    /**
+     * Check if this is resolved.
+     *
+     * @return true when this has been resolved
+     */
     public boolean isResolved() {
        return resolved;
     }
diff --git a/src/org/apache/fop/area/inline/Viewport.java b/src/org/apache/fop/area/inline/Viewport.java
index 6f48d7d22..d4a507890 100644
--- a/src/org/apache/fop/area/inline/Viewport.java
+++ b/src/org/apache/fop/area/inline/Viewport.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -13,38 +13,79 @@ import org.apache.fop.render.Renderer;
 import java.io.IOException;
 import java.awt.geom.Rectangle2D;
 
+/**
+ * Inline viewport area.
+ * This is an inline-level viewport area for inline container,
+ * external graphic and instream foreign object. This viewport
+ * holds the area and positions it.
+ */
 public class Viewport extends InlineArea {
     // contents could be container, foreign object or image
-    Area content;
-    // an inline-level viewport area for graphic and instream foreign object
-    boolean clip = false;
-    // position relative to this area
-    Rectangle2D contentPosition;
+    private Area content;
+    // clipping for the viewport
+    private boolean clip = false;
+    // position of the cild area relative to this area
+    private Rectangle2D contentPosition;
 
+    /**
+     * Create a new viewport area with the content area.
+     *
+     * @param child the child content area of this viewport
+     */
     public Viewport(Area child) {
         content = child;
     }
 
+    /**
+     * Set the clip of this viewport.
+     *
+     * @param c true if this viewport should clip
+     */
     public void setClip(boolean c) {
         clip = c;
     }
 
+    /**
+     * Get the clip of this viewport.
+     *
+     * @return true if this viewport should clip
+     */
     public boolean getClip() {
         return clip;
     }
 
+    /**
+     * Set the position and size of the content of this viewport.
+     *
+     * @param cp the position and size to place the content
+     */
     public void setContentPosition(Rectangle2D cp) {
         contentPosition = cp;
     }
 
+    /**
+     * Get the position and size of the content of this viewport.
+     *
+     * @return the position and size to place the content
+     */
     public Rectangle2D getContentPosition() {
         return contentPosition;
     }
 
+    /**
+     * Get the content area for this viewport.
+     *
+     * @return the content area
+     */
     public Area getContent() {
         return content;
     }
 
+    /**
+     * Render this inline area.
+     *
+     * @param renderer the renderer to render this inline area
+     */
     public void render(Renderer renderer) {
         renderer.renderViewport(this);
     }
@@ -66,7 +107,9 @@ public class Viewport extends InlineArea {
     throws IOException, ClassNotFoundException {
         if (in.readBoolean()) {
             contentPosition = new Rectangle2D.Float(in.readFloat(),
-                                                    in.readFloat(), in.readFloat(), in.readFloat());
+                                                    in.readFloat(),
+                                                    in.readFloat(),
+                                                    in.readFloat());
         }
         clip = in.readBoolean();
         content = (Area) in.readObject();
diff --git a/src/org/apache/fop/area/inline/Word.java b/src/org/apache/fop/area/inline/Word.java
index 55a3231d9..8f8248900 100644
--- a/src/org/apache/fop/area/inline/Word.java
+++ b/src/org/apache/fop/area/inline/Word.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -12,8 +12,8 @@ import org.apache.fop.render.Renderer;
 public class Word extends InlineArea {
 
     // character info: font, char spacing, colour, baseline
-    String word;
-    int iWSadjust = 0;
+    private String word;
+    private int iWSadjust = 0;
 
     public void render(Renderer renderer) {
         renderer.renderWord(this);
@@ -35,3 +35,4 @@ public class Word extends InlineArea {
         this.iWSadjust = iWSadjust;
     }
 }
+