Fixed checkstyle violations

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

11 files changed, 518 insertions, 225 deletions

diff --git a/src/org/apache/fop/render/AbstractRenderer.java b/src/org/apache/fop/render/AbstractRenderer.java
index a4d16defe..42660c85f 100644
--- a/src/org/apache/fop/render/AbstractRenderer.java
+++ b/src/org/apache/fop/render/AbstractRenderer.java
@@ -1,127 +1,177 @@
 /*
  * $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.render;
 
-// FOP
-import org.apache.fop.apps.FOPException;
-import org.apache.fop.area.*;
-import org.apache.fop.area.inline.*;
-import org.apache.fop.area.inline.Character;
-import org.apache.fop.fo.FOUserAgent;
-
-// Avalon
-import org.apache.avalon.framework.logger.AbstractLogEnabled;
-
 // Java
 import java.awt.geom.Rectangle2D;
 import java.io.IOException;
-import java.io.OutputStream;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Iterator;
 
+// FOP
+import org.apache.fop.apps.FOPException;
+import org.apache.fop.fo.FOUserAgent;
+import org.apache.fop.area.Area;
+import org.apache.fop.area.BeforeFloat;
+import org.apache.fop.area.Block;
+import org.apache.fop.area.BlockViewport;
+import org.apache.fop.area.BodyRegion;
+import org.apache.fop.area.CTM;
+import org.apache.fop.area.Flow;
+import org.apache.fop.area.Footnote;
+import org.apache.fop.area.LineArea;
+import org.apache.fop.area.MainReference;
+import org.apache.fop.area.Span;
+import org.apache.fop.area.Page;
+import org.apache.fop.area.PageViewport;
+import org.apache.fop.area.RegionViewport;
+import org.apache.fop.area.RegionReference;
+import org.apache.fop.area.Title;
+import org.apache.fop.area.TreeExt;
+import org.apache.fop.area.inline.Container;
+import org.apache.fop.area.inline.ForeignObject;
+import org.apache.fop.area.inline.Image;
+import org.apache.fop.area.inline.InlineArea;
+import org.apache.fop.area.inline.InlineParent;
+import org.apache.fop.area.inline.Leader;
+import org.apache.fop.area.inline.Space;
+import org.apache.fop.area.inline.Viewport;
+import org.apache.fop.area.inline.Word;
+import org.apache.fop.area.inline.Character;
+
+// Avalon
+import org.apache.avalon.framework.logger.AbstractLogEnabled;
+
 /**
- * Abstract base class for all renderers.
- * The Abstract renderer does all the top level processing
- * of the area tree and adds some abstract methods to handle
- * viewports. This keeps track of the current block and inline
- * position.
+ * Abstract base class for all renderers. The Abstract renderer does all the
+ * top level processing of the area tree and adds some abstract methods to
+ * handle viewports. This keeps track of the current block and inline position.
  */
-public abstract class AbstractRenderer extends AbstractLogEnabled implements Renderer {
+public abstract class AbstractRenderer extends AbstractLogEnabled
+         implements Renderer {
+
+    /**
+     * user agent
+     */
     protected FOUserAgent userAgent;
+
+    /**
+     * renderer configuration
+     */
     protected HashMap options;
 
-    // block progression position
+    /**
+     * block progression position
+     */
     protected int currentBPPosition = 0;
 
-    // inline progression position
+    /**
+     * inline progression position
+     */
     protected int currentIPPosition = 0;
 
+    /**
+     * current inline progression position in block
+     */
     protected int currentBlockIPPosition = 0;
 
+    /** @see org.apache.fop.render.Renderer */
     public void setUserAgent(FOUserAgent agent) {
         userAgent = agent;
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void setOptions(HashMap opt) {
         options = opt;
     }
 
     /**
-     * Check if this renderer supports out of order rendering.
-     * If this renderer supports out of order rendering then it
-     * means that the pages that are not ready will be prepared
-     * and a future page will be rendered.
+     * Check if this renderer supports out of order rendering. If this renderer
+     * supports out of order rendering then it means that the pages that are
+     * not ready will be prepared and a future page will be rendered.
+     *
+     * @return   True if the renderer supports out of order rendering
+     * @see      org.apache.fop.render.Renderer
      */
     public boolean supportsOutOfOrder() {
         return false;
     }
 
     /**
-     * Render tree extension.
+     * @param ext  @todo Description of the Parameter
+     * @see        org.apache.fop.render.Renderer
      */
-    public void renderExtension(TreeExt ext) {
-    }
+    public void renderExtension(TreeExt ext) { }
 
     /**
-     * Prepare a page for rendering.
-     * This is called if the renderer supports out of order rendering.
-     * The renderer should prepare the page so that a page further on
-     * in the set of pages can be rendered. The body of the page should
-     * not be rendered. The page will be rendered at a later time
+     * Prepare a page for rendering. This is called if the renderer supports
+     * out of order rendering. The renderer should prepare the page so that a
+     * page further on in the set of pages can be rendered. The body of the
+     * page should not be rendered. The page will be rendered at a later time
      * by the call to render page.
+     *
+     * @see org.apache.fop.render.Renderer
      */
-    public void preparePage(PageViewport page) {
-    }
+    public void preparePage(PageViewport page) { }
 
     /**
-     * Utility method to convert a page sequence title to a string.
-     * Some renderers may only be able to use a string title.
-     * A title is a sequence of inline areas that this method
-     * attempts to convert to an equivalent string.
+     * Utility method to convert a page sequence title to a string. Some
+     * renderers may only be able to use a string title. A title is a sequence
+     * of inline areas that this method attempts to convert to an equivalent
+     * string.
+     *
+     * @param title  The Title to convert
+     * @return       An expanded string representing the title
      */
-    public String convertTitleToString(Title title) {
-        String str = "";
+    protected String convertTitleToString(Title title) {
         List children = title.getInlineAreas();
-        str = convertToString(children);
+        String str = convertToString(children);
         return str.trim();
     }
 
     private String convertToString(List children) {
-        String str = "";
+        StringBuffer sb = new StringBuffer();
         for (int count = 0; count < children.size(); count++) {
             InlineArea inline = (InlineArea) children.get(count);
             if (inline instanceof Character) {
-                str += ((Character) inline).getChar();
+                sb.append(((Character) inline).getChar());
             } else if (inline instanceof Word) {
-                str += ((Word) inline).getWord();
+                sb.append(((Word) inline).getWord());
             } else if (inline instanceof InlineParent) {
-                str += convertToString(
-                         ((InlineParent) inline).getChildAreas());
+                sb.append(convertToString(
+                        ((InlineParent) inline).getChildAreas()));
             } else {
-                str += " ";
+                sb.append(" ");
             }
         }
-        return str;
+        return sb.toString();
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void startPageSequence(Title seqTitle) {
+        //do nothing
     }
 
     // normally this would be overriden to create a page in the
     // output
-    public void renderPage(PageViewport page) throws IOException,
-    FOPException {
+    /** @see org.apache.fop.render.Renderer */
+    public void renderPage(PageViewport page)
+        throws IOException, FOPException {
 
         Page p = page.getPage();
         renderPageAreas(p);
     }
 
+    /**
+     * Renders page areas.
+     *
+     * @param page  The page whos page areas are to be rendered
+     */
     protected void renderPageAreas(Page page) {
         RegionViewport viewport;
         viewport = page.getRegion(RegionReference.BEFORE);
@@ -134,19 +184,24 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         renderRegionViewport(viewport);
         viewport = page.getRegion(RegionReference.AFTER);
         renderRegionViewport(viewport);
-
     }
 
-    // the region may clip the area and it establishes
-    // a position from where the region is placed
+    /**
+     * Renders a region viewport. <p>
+     *
+     * The region may clip the area and it establishes a position from where
+     * the region is placed.</p>
+     *
+     * @param port  The region viewport to be rendered
+     */
     protected void renderRegionViewport(RegionViewport port) {
         if (port != null) {
             Rectangle2D view = port.getViewArea();
             // The CTM will transform coordinates relative to
             // this region-reference area into page coords, so
             // set origin for the region to 0,0.
-            currentBPPosition = 0; // (int) (view.getY() / 1000);
-            currentIPPosition = 0; // (int) (view.getX() / 1000);
+            currentBPPosition = 0;// (int) (view.getY() / 1000);
+            currentIPPosition = 0;// (int) (view.getX() / 1000);
             currentBlockIPPosition = currentIPPosition;
 
             RegionReference region = port.getRegion();
@@ -160,10 +215,23 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
+    /**
+     * @todo Description of the Method
+     *
+     * @param ctm  The coordinate transformation matrix to use
+     */
     protected void startVParea(CTM ctm) { }
 
+    /**
+     * @todo Description of the Method
+     */
     protected void endVParea() { }
 
+    /**
+     * Renders a region reference area.
+     *
+     * @param region  The region reference area
+     */
     protected void renderRegion(RegionReference region) {
         List blocks = region.getBlocks();
 
@@ -171,6 +239,11 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
 
     }
 
+    /**
+     * Renders a body region area.
+     *
+     * @param region  The body region
+     */
     protected void renderBodyRegion(BodyRegion region) {
         BeforeFloat bf = region.getBeforeFloat();
         if (bf != null) {
@@ -186,6 +259,11 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
+    /**
+     * Renders a before float area.
+     *
+     * @param bf  The before float area
+     */
     protected void renderBeforeFloat(BeforeFloat bf) {
         List blocks = bf.getBlocks();
         if (blocks != null) {
@@ -197,6 +275,11 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
+    /**
+     * Renders a footnote
+     *
+     * @param footnote  The footnote
+     */
     protected void renderFootnote(Footnote footnote) {
         List blocks = footnote.getBlocks();
         if (blocks != null) {
@@ -208,10 +291,17 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
-    // the main reference area contains a list of spans that are
-    // stacked on the page
-    // the spans contain a list of normal flow reference areas
-    // that are positioned into columns.
+    /**
+     * Renders the main reference area.
+     * <p>
+     * The main reference area contains a list of spans that are
+     * stacked on the page.
+     * The spans contain a list of normal flow reference areas
+     * that are positioned into columns.
+     * </p>
+     *
+     * @param mr  The main reference area
+     */
     protected void renderMainReference(MainReference mr) {
         int saveIPPos = currentIPPosition;
 
@@ -219,9 +309,9 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         List spans = mr.getSpans();
         for (int count = 0; count < spans.size(); count++) {
             span = (Span) spans.get(count);
-            int offset = (mr.getWidth() -
-                          (span.getColumnCount() - 1) * mr.getColumnGap()) /
-                         span.getColumnCount() + mr.getColumnGap();
+            int offset = (mr.getWidth()
+                    - (span.getColumnCount() - 1) * mr.getColumnGap())
+                    / span.getColumnCount() + mr.getColumnGap();
             for (int c = 0; c < span.getColumnCount(); c++) {
                 Flow flow = (Flow) span.getFlow(c);
 
@@ -233,13 +323,23 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
-    // the normal flow reference area contains stacked blocks
+    /**
+     * Renders a flow reference area.
+     *
+     * @param flow  The flow reference area
+     */
     protected void renderFlow(Flow flow) {
+        // the normal flow reference area contains stacked blocks
         List blocks = flow.getBlocks();
         renderBlocks(blocks);
 
     }
 
+    /**
+     * Renders a block area.
+     *
+     * @param block  The block area
+     */
     protected void renderBlock(Block block) {
         List children = block.getChildAreas();
         if (children == null) {
@@ -251,6 +351,12 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
+    /**
+     * Renders a block viewport.
+     *
+     * @param bv        The block viewport
+     * @param children  The children to render within the block viewport
+     */
     protected void renderBlockViewport(BlockViewport bv, List children) {
         // clip and position viewport if necessary
         if (bv.getPositioning() == Block.ABSOLUTE) {
@@ -275,8 +381,14 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         }
     }
 
-    // a line area may have grouped styling for its children
-    // such as underline, background
+    /**
+     * Renders a line area. <p>
+     *
+     * A line area may have grouped styling for its children such as underline,
+     * background.</p>
+     *
+     * @param line  The line area
+     */
     protected void renderLineArea(LineArea line) {
         List children = line.getInlineAreas();
 
@@ -284,9 +396,9 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
             InlineArea inline = (InlineArea) children.get(count);
             inline.render(this);
         }
-
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderViewport(Viewport viewport) {
         Area content = viewport.getContent();
         int saveBP = currentBPPosition;
@@ -303,9 +415,19 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         currentBPPosition = saveBP;
     }
 
+    /**
+     * Renders an image area.
+     *
+     * @param image  The image
+     * @param pos    The target position of the image
+     * @todo Make renderImage() protected
+     */
     public void renderImage(Image image, Rectangle2D pos) {
+        // Default: do nothing.
+        // Some renderers (ex. Text) don't support images.
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderContainer(Container cont) {
         int saveIP = currentIPPosition;
         currentIPPosition = currentBlockIPPosition;
@@ -319,30 +441,43 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         currentBPPosition = saveBP;
     }
 
+    /**
+     * Renders a foreign object area.
+     *
+     * @param fo   The foreign object area
+     * @param pos  The target position of the foreign object
+     * @todo Make renderForeignObject() protected
+     */
     public void renderForeignObject(ForeignObject fo, Rectangle2D pos) {
-
+        // Default: do nothing.
+        // Some renderers (ex. Text) don't support foreign objects.
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderCharacter(Character ch) {
         currentBlockIPPosition += ch.getWidth();
     }
 
-    // an inline space moves the inline progression position
-    // for the current block by the width or height of the space
-    // it may also have styling (only on this object) that needs
-    // handling
+    /** @see org.apache.fop.render.Renderer */
     public void renderInlineSpace(Space space) {
+        // an inline space moves the inline progression position
+        // for the current block by the width or height of the space
+        // it may also have styling (only on this object) that needs
+        // handling
         currentBlockIPPosition += space.getWidth();
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderLeader(Leader area) {
         currentBlockIPPosition += area.getWidth();
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderWord(Word word) {
         currentBlockIPPosition += word.getWidth();
     }
 
+    /** @see org.apache.fop.render.Renderer */
     public void renderInlineParent(InlineParent ip) {
         int saveIP = currentBlockIPPosition;
         Iterator iter = ip.getChildAreas().iterator();
@@ -352,6 +487,11 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
         currentBlockIPPosition = saveIP + ip.getWidth();
     }
 
+    /**
+     * Renders a list of block areas.
+     *
+     * @param blocks  The block areas
+     */
     protected void renderBlocks(List blocks) {
         for (int count = 0; count < blocks.size(); count++) {
             Object obj = blocks.get(count);
@@ -362,10 +502,11 @@ public abstract class AbstractRenderer extends AbstractLogEnabled implements Ren
                 // of the line, each inline object is offset from there
                 LineArea line = (LineArea) obj;
                 currentBlockIPPosition =
-                  currentIPPosition + line.getStartIndent();
+                        currentIPPosition + line.getStartIndent();
                 renderLineArea(line);
                 currentBPPosition += line.getHeight();
             }
         }
     }
+
 }
diff --git a/src/org/apache/fop/render/PrintRenderer.java b/src/org/apache/fop/render/PrintRenderer.java
index 153ccc89b..4420361cb 100644
--- a/src/org/apache/fop/render/PrintRenderer.java
+++ b/src/org/apache/fop/render/PrintRenderer.java
@@ -1,55 +1,41 @@
 /*
  * $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.render;
 
 // FOP
-import org.apache.fop.pdf.PDFPathPaint;
-import org.apache.fop.pdf.PDFColor;
-import org.apache.fop.apps.FOPException;
-import org.apache.fop.fo.properties.*;
-import org.apache.fop.datatypes.*;
 import org.apache.fop.render.pdf.FontSetup;
 import org.apache.fop.layout.FontInfo;
 
 // Java
 import java.io.IOException;
 import java.io.OutputStream;
-import java.util.Enumeration;
 
-/**
- * Abstract base class of "Print" type renderers.
- * 
- */
+/** Abstract base class of "Print" type renderers.  */
 public abstract class PrintRenderer extends AbstractRenderer {
+
+    /** Font configuration */
     protected FontInfo fontInfo;
 
     /**
-     * set up the font info
-     * 
-     * @param fontInfo font info to set up
+     * Set up the font info
+     *
+     * @param fontInfo  font info to set up
      */
     public void setupFontInfo(FontInfo fontInfo) {
         this.fontInfo = fontInfo;
         FontSetup.setup(fontInfo, null);
     }
 
-    /**
-     *
-     */
+    /** @see org.apache.fop.render.Renderer */
     public void startRenderer(OutputStream outputStream)
-    throws IOException {}
+        throws IOException { }
 
-    /**
-     *
-     */
+    /** @see org.apache.fop.render.Renderer */
     public void stopRenderer()
-    throws IOException
-    {
-    }
+        throws IOException { }
 
 }
diff --git a/src/org/apache/fop/render/Renderer.java b/src/org/apache/fop/render/Renderer.java
index 0bddcea97..9a489c7d7 100644
--- a/src/org/apache/fop/render/Renderer.java
+++ b/src/org/apache/fop/render/Renderer.java
@@ -1,84 +1,197 @@
 /*
  * $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.render;
 
-// FOP
-import org.apache.fop.apps.FOPException;
-import org.apache.fop.area.*;
-import org.apache.fop.area.inline.*;
-import org.apache.fop.layout.FontInfo;
-import org.apache.fop.fo.FOUserAgent;
-
 // Java
 import java.io.OutputStream;
 import java.io.IOException;
 import java.util.HashMap;
 
+// FOP
+import org.apache.fop.apps.FOPException;
+import org.apache.fop.area.PageViewport;
+import org.apache.fop.area.Title;
+import org.apache.fop.area.TreeExt;
+import org.apache.fop.area.inline.Container;
+import org.apache.fop.area.inline.InlineParent;
+import org.apache.fop.area.inline.Leader;
+import org.apache.fop.area.inline.Space;
+import org.apache.fop.area.inline.Viewport;
+import org.apache.fop.area.inline.Word;
+import org.apache.fop.layout.FontInfo;
+import org.apache.fop.fo.FOUserAgent;
+
 /**
- * Interface implemented by all renderers.
- * This interface is used to control the rendering of pages
- * and to let block and inline level areas call the appropriate
- * method to render themselves
+ * Interface implemented by all renderers. This interface is used to control
+ * the rendering of pages and to let block and inline level areas call the
+ * appropriate method to render themselves. <p>
+ *
+ * A Renderer implementation takes areas/spaces and produces output in some
+ * format.</p> <p>
  *
- * a Renderer implementation takes areas/spaces and produces output in
- * some format.
+ * Typically, most renderers are subclassed from FOP's abstract implementations
+ * ({@link AbstractRenderer}, {@link PrintRenderer}) which already handle a lot
+ * of things letting you concentrate on the details of the output format.
  */
 public interface Renderer {
 
-    public static final String ROLE = Renderer.class.getName();
+    /**
+     * Role constant for Avalon.
+     */
+    String ROLE = Renderer.class.getName();
+
 
+    /**
+     * Initiates the rendering phase.
+     *
+     * @param outputStream     The OutputStream to use for output
+     * @exception IOException  If an I/O error occurs
+     */
+    void startRenderer(OutputStream outputStream)
+        throws IOException;
 
-    public void startRenderer(OutputStream outputStream) throws IOException;
+    /**
+     * Signals the end of the rendering phase.
+     *
+     * @exception IOException  If an I/O error occurs
+     */
+    void stopRenderer()
+        throws IOException;
 
-    public void stopRenderer() throws IOException;
+    /**
+     * Set the User Agent.
+     *
+     * @param agent  The User Agent
+     */
+    void setUserAgent(FOUserAgent agent);
 
     /**
-     * Set the User Agent
+     * Set up the given FontInfo.
+     *
+     * @param fontInfo  The fonts
      */
-    public void setUserAgent(FOUserAgent agent);
+    void setupFontInfo(FontInfo fontInfo);
 
     /**
-     * set up the given FontInfo
+     * Set up renderer options.
+     *
+     * @param options  The Configuration for the renderer
      */
-    public void setupFontInfo(FontInfo fontInfo);
+    void setOptions(HashMap options);
 
     /**
-     * set up renderer options
+     * Set the producer of the rendering. If this method isn't called the
+     * renderer uses a default. Note: Not all renderers support this feature.
+     *
+     * @param producer  The name of the producer (normally "FOP") to be
+     *      embedded in the generated file.
      */
-    public void setOptions(HashMap options);
+    void setProducer(String producer);
 
     /**
-     * set the producer of the rendering
+     * Reports if out of order rendering is supported. <p>
+     *
+     * Normally, all pages of a document are rendered in their natural order
+     * (page 1, page 2, page 3 etc.). Some output formats (such as PDF) allow
+     * pages to be output in random order. This is helpful to reduce resource
+     * strain on the system because a page that cannot be fully resolved
+     * doesn't block subsequent pages that are already fully resolved. </p>
+     *
+     * @return   True if this renderer supports out of order rendering.
      */
-    public void setProducer(String producer);
+    boolean supportsOutOfOrder();
 
-    public boolean supportsOutOfOrder();
+    /**
+     * Tells the renderer to render an extension element.
+     *
+     * @param ext  The extension element to be rendered
+     */
+    void renderExtension(TreeExt ext);
 
-    public void renderExtension(TreeExt ext);
+    /**
+     * This is called if the renderer supports out of order rendering. The
+     * renderer should prepare the page so that a page further on in the set of
+     * pages can be rendered. The body of the page should not be rendered. The
+     * page will be rendered at a later time by the call to {@link
+     * #renderPage(PageViewport)}.
+     *
+     * @param page  The page viewport to use
+     */
+    void preparePage(PageViewport page);
 
-    public void preparePage(PageViewport page);
+    /**
+     * Tells the renderer that a new page sequence starts.
+     *
+     * @param seqTitle  The title of the page sequence
+     */
+    void startPageSequence(Title seqTitle);
 
-    public void startPageSequence(Title seqTitle);
+    /**
+     * Tells the renderer to render a particular page. A renderer typically
+     * reponds by packing up the current page and writing it immediately to the
+     * output device.
+     *
+     * @param page              The page to be rendered
+     * @exception IOException   if an I/O error occurs
+     * @exception FOPException  if a FOP interal error occurs.
+     */
+    void renderPage(PageViewport page)
+        throws IOException, FOPException;
 
-    public void renderPage(PageViewport page) throws IOException, FOPException;
+    /**
+     * Tells the renderer to render an inline viewport. It sets up clipping as
+     * necessary.
+     *
+     * @param viewport  The viewport area
+     */
+    void renderViewport(Viewport viewport);
 
-    public void renderViewport(Viewport viewport);
+    /**
+     * Tells the renderer to render an inline container.
+     *
+     * @param cont  The inline container area
+     */
+    void renderContainer(Container cont);
 
-    public void renderContainer(Container cont);
+    /**
+     * Tells the renderer to render an inline word.
+     *
+     * @param area  The word area
+     */
+    void renderWord(Word area);
 
-    public void renderWord(Word area);
+    /**
+     * Tells the renderer to render an inline parent area.
+     *
+     * @param ip  The inline parent area
+     */
+    void renderInlineParent(InlineParent ip);
 
-    public void renderInlineParent(InlineParent ip);
+    /**
+     * Tells the renderer to render an inline character.
+     *
+     * @param ch  The inline character
+     */
+    void renderCharacter(
+            org.apache.fop.area.inline.Character ch);
 
-    public void renderCharacter(
-              org.apache.fop.area.inline.Character ch);
+    /**
+     * Tells the renderer to render an inline space.
+     *
+     * @param space  The inline space
+     */
+    void renderInlineSpace(Space space);
 
-    public void renderInlineSpace(Space space);
+    /**
+     * Tells the renderer to render an inline leader area.
+     *
+     * @param area  The inline leader area.
+     */
+    void renderLeader(Leader area);
 
-    public void renderLeader(Leader area);
 }
 
diff --git a/src/org/apache/fop/render/RendererContext.java b/src/org/apache/fop/render/RendererContext.java
index 911c9baab..52c242dd9 100644
--- a/src/org/apache/fop/render/RendererContext.java
+++ b/src/org/apache/fop/render/RendererContext.java
@@ -1,45 +1,80 @@
 /*
  * $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.render;
 
-import org.apache.fop.fo.FOUserAgent;
+//Java
+import java.util.Map;
 
-import java.util.HashMap;
+//FOP
+import org.apache.fop.fo.FOUserAgent;
 
 /**
- * The Render Context for external handlers.
- * This provides a rendering context so that external handlers
- * can get information to be able to render to the render target.
+ * The Render Context for external handlers. This provides a rendering context
+ * so that external handlers can get information to be able to render to the
+ * render target.
  */
 public class RendererContext {
-    String mime;
-    FOUserAgent userAgent;
-    HashMap props = new HashMap();
 
+    private String mime;
+    private FOUserAgent userAgent;
+    private Map props = new java.util.HashMap();
+
+    /**
+     * Contructor for this class. It takes a MIME type as parameter.
+     *
+     * @param m  The MIME type of the output that's generated.
+     */
     public RendererContext(String m) {
         mime = m;
     }
 
+    /**
+     * Returns the MIME type associated with this RendererContext.
+     *
+     * @return   The MIME type (ex. application/pdf)
+     */
     public String getMimeType() {
         return mime;
     }
 
+    /**
+     * Sets the user agent.
+     *
+     * @param ua  The user agent
+     */
     public void setUserAgent(FOUserAgent ua) {
         userAgent = ua;
     }
 
+    /**
+     * Returns the user agent.
+     *
+     * @return   The user agent
+     */
     public FOUserAgent getUserAgent() {
         return userAgent;
     }
 
+    /**
+     * Sets a property on the RendererContext.
+     *
+     * @param name  The key of the property
+     * @param val   The value of the property
+     */
     public void setProperty(String name, Object val) {
         props.put(name, val);
     }
 
+    /**
+     * Returns a property from the RendererContext.
+     *
+     * @param prop  The key of the property to return.
+     * @return      The requested value, <code>null</code> if it doesn't exist.
+     */
     public Object getProperty(String prop) {
         return props.get(prop);
     }
diff --git a/src/org/apache/fop/render/XMLHandler.java b/src/org/apache/fop/render/XMLHandler.java
index 1bdf05729..e5437c015 100644
--- a/src/org/apache/fop/render/XMLHandler.java
+++ b/src/org/apache/fop/render/XMLHandler.java
@@ -1,24 +1,33 @@
 /*
  * $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.render;
 
 import org.w3c.dom.Document;
 
 /**
+ * This interface is implemented by classes that can handle a certain type
+ * of foreign objects.
  */
 public interface XMLHandler {
 
     /**
-     * Handle an external xml document inside a Foreign Object Area
-     * This may throw an exception if for some reason it cannot be handled.
-     * The caller is expected to deal with this exception.
+     * Handle an external xml document inside a Foreign Object Area. <p>
+     *
+     * This may throw an exception if for some reason it cannot be handled. The
+     * caller is expected to deal with this exception.</p>
+     *
+     * @param context        The RendererContext (contains the user agent)
+     * @param doc            A DOM containing the foreign object to be
+     *      processed
+     * @param ns             The Namespace of the foreign object
+     * @exception Exception  If an error occurs during processing.
      */
-    public void handleXML(RendererContext context, Document doc,
-                          String ns) throws Exception;
+    void handleXML(RendererContext context, Document doc, String ns)
+        throws Exception;
+
 }
 
diff --git a/src/org/apache/fop/render/ps/ASCII85OutputStream.java b/src/org/apache/fop/render/ps/ASCII85OutputStream.java
index 80adf8dab..1b4473539 100644
--- a/src/org/apache/fop/render/ps/ASCII85OutputStream.java
+++ b/src/org/apache/fop/render/ps/ASCII85OutputStream.java
@@ -25,10 +25,10 @@ public class ASCII85OutputStream extends FilterOutputStream
     private static final int EOL           = 0x0A; //"\n"
     private static final byte[] EOD        = {0x7E, 0x3E}; //"~>"
 
-    private static final long base85_4 = 85;
-    private static final long base85_3 = base85_4 * base85_4;
-    private static final long base85_2 = base85_3 * base85_4;
-    private static final long base85_1 = base85_2 * base85_4;
+    private static final long BASE85_4 = 85;
+    private static final long BASE85_3 = BASE85_4 * BASE85_4;
+    private static final long BASE85_2 = BASE85_3 * BASE85_4;
+    private static final long BASE85_1 = BASE85_2 * BASE85_4;
 
     private static final boolean DEBUG = false;
 
@@ -38,11 +38,13 @@ public class ASCII85OutputStream extends FilterOutputStream
     private int bw = 0;
 
 
+    /** @see java.io.FilterOutputStream **/
     public ASCII85OutputStream(OutputStream out) {
         super(out);
     }
 
 
+    /** @see java.io.FilterOutputStream **/
     public void write(int b) throws IOException {
         if (pos == 0) {
             buffer += (b << 24) & 0xff000000L;
@@ -82,10 +84,14 @@ public class ASCII85OutputStream extends FilterOutputStream
     private void checkedWrite(byte[] buf , int len) throws IOException {
         if (posinline + len > 80) {
             int firstpart = len - (posinline + len - 80);
-            if (firstpart > 0) out.write(buf, 0, firstpart);
+            if (firstpart > 0) {
+                out.write(buf, 0, firstpart);
+            }
             out.write(EOL); bw++;
             int rest = len - firstpart;
-            if (rest > 0) out.write(buf, firstpart, rest);
+            if (rest > 0) {
+                out.write(buf, firstpart, rest);
+            }
             posinline = rest;
         } else {
             out.write(buf, 0, len);
@@ -113,17 +119,18 @@ public class ASCII85OutputStream extends FilterOutputStream
             if (word < 0) {
                 word = -word;
             }
-            byte c1 = (byte)((word / base85_1) & 0xFF);
-            byte c2 = (byte)(((word - (c1 * base85_1)) / base85_2) & 0xFF);
+            byte c1 = (byte)((word / BASE85_1) & 0xFF);
+            byte c2 = (byte)(((word - (c1 * BASE85_1)) / BASE85_2) & 0xFF);
             byte c3 =
-                (byte)(((word - (c1 * base85_1) - (c2 * base85_2)) / base85_3)
-                       & 0xFF);
+                (byte)(((word - (c1 * BASE85_1) - (c2 * BASE85_2))
+                        / BASE85_3) & 0xFF);
             byte c4 =
-                (byte)(((word - (c1 * base85_1) - (c2 * base85_2) - (c3 * base85_3)) / base85_4)
-                       & 0xFF);
+                (byte)(((word - (c1 * BASE85_1) - (c2 * BASE85_2) - (c3 * BASE85_3))
+                        / BASE85_4) & 0xFF);
             byte c5 =
-                (byte)(((word - (c1 * base85_1) - (c2 * base85_2) - (c3 * base85_3) - (c4 * base85_4)))
-                       & 0xFF);
+                (byte)(((word - (c1 * BASE85_1) - (c2 * BASE85_2) - (c3 * BASE85_3)
+                        - (c4 * BASE85_4)))
+                        & 0xFF);
 
             byte[] ret = {
                 (byte)(c1 + START), (byte)(c2 + START),
@@ -144,6 +151,7 @@ public class ASCII85OutputStream extends FilterOutputStream
     }
 
 
+    /** @see org.apache.fop.render.ps.Finalizable **/
     public void finalizeStream() throws IOException {
         // now take care of the trailing few bytes.
         // with n leftover bytes, we append 0 bytes to make a full group of 4
@@ -191,6 +199,7 @@ public class ASCII85OutputStream extends FilterOutputStream
     }
 
 
+    /** @see java.io.FilterOutputStream **/
     public void close() throws IOException {
         finalizeStream();
         super.close();
diff --git a/src/org/apache/fop/render/ps/ASCIIHexOutputStream.java b/src/org/apache/fop/render/ps/ASCIIHexOutputStream.java
index af37a73b4..34b2c5192 100644
--- a/src/org/apache/fop/render/ps/ASCIIHexOutputStream.java
+++ b/src/org/apache/fop/render/ps/ASCIIHexOutputStream.java
@@ -16,32 +16,39 @@ import java.io.IOException;
  * @author <a href="mailto:jeremias.maerki@outline.ch">Jeremias Maerki</a>
  * @version $Id$
  */
-public class ASCIIHexOutputStream extends FilterOutputStream {
+public class ASCIIHexOutputStream extends FilterOutputStream
+        implements Finalizable {
 
     private static final int EOL   = 0x0A; //"\n"
     private static final int EOD   = 0x3E; //">"
     private static final int ZERO  = 0x30; //"0"
     private static final int NINE  = 0x39; //"9"
     private static final int A     = 0x41; //"A"
-    private static final int ADIFF = A - NINE -1;
+    private static final int ADIFF = A - NINE - 1;
 
     private int posinline = 0;
 
 
+    /** @see java.io.FilterOutputStream **/
     public ASCIIHexOutputStream(OutputStream out) {
         super(out);
     }
 
 
+    /** @see java.io.FilterOutputStream **/
     public void write(int b) throws IOException {
         b &= 0xFF;
 
         int digit1 = ((b & 0xF0) >> 4) + ZERO;
-        if (digit1 > NINE) digit1 += ADIFF;
+        if (digit1 > NINE) {
+            digit1 += ADIFF;
+        }
         out.write(digit1);
 
         int digit2 = (b & 0x0F) + ZERO;
-        if (digit2 > NINE) digit2 += ADIFF;
+        if (digit2 > NINE) {
+            digit2 += ADIFF;
+        }
         out.write(digit2);
 
         posinline++;
@@ -58,6 +65,7 @@ public class ASCIIHexOutputStream extends FilterOutputStream {
     }
 
 
+    /** @see org.apache.fop.render.ps.Finalizable **/
     public void finalizeStream() throws IOException {
         checkLineWrap();
         //Write closing character ">"
@@ -65,11 +73,12 @@ public class ASCIIHexOutputStream extends FilterOutputStream {
 
         flush();
         if (out instanceof Finalizable) {
-            ((Finalizable)out).finalizeStream();
+            ((Finalizable) out).finalizeStream();
         }
     }
 
 
+    /** @see java.io.FilterOutputStream **/
     public void close() throws IOException {
         finalizeStream();
         super.close();
diff --git a/src/org/apache/fop/render/ps/Finalizable.java b/src/org/apache/fop/render/ps/Finalizable.java
index d7c77d668..83b80b810 100644
--- a/src/org/apache/fop/render/ps/Finalizable.java
+++ b/src/org/apache/fop/render/ps/Finalizable.java
@@ -24,7 +24,7 @@ public interface Finalizable {
      *
      * @exception java.io.IOException  In case of an IO problem
      */
-    public void finalizeStream()
+    void finalizeStream()
         throws java.io.IOException;
 
 }
diff --git a/src/org/apache/fop/render/ps/FlateEncodeOutputStream.java b/src/org/apache/fop/render/ps/FlateEncodeOutputStream.java
index e6d96b8e9..ca65a778a 100644
--- a/src/org/apache/fop/render/ps/FlateEncodeOutputStream.java
+++ b/src/org/apache/fop/render/ps/FlateEncodeOutputStream.java
@@ -7,12 +7,12 @@
 package org.apache.fop.render.ps;
 
 import java.io.OutputStream;
-import java.io.FilterOutputStream;
 import java.io.IOException;
 
 /**
  * This class applies a FlateEncode filter to the stream. It is basically the
- * normal DeflaterOutputStream except now conformi
+ * normal DeflaterOutputStream except now also implementing the Finalizable
+ * interface.
  *
  * @author <a href="mailto:jeremias.maerki@outline.ch">Jeremias Maerki</a>
  * @version $Id$
@@ -21,11 +21,13 @@ public class FlateEncodeOutputStream extends java.util.zip.DeflaterOutputStream
             implements Finalizable {
 
 
+    /** @see java.util.zip.DeflaterOutputStream **/
     public FlateEncodeOutputStream(OutputStream out) {
         super(out);
     }
 
 
+    /** @see org.apache.fop.render.ps.Finalizable **/
     public void finalizeStream() throws IOException {
         finish();
         flush();
diff --git a/src/org/apache/fop/render/ps/PSStream.java b/src/org/apache/fop/render/ps/PSStream.java
index 2643a6c5a..2e1c624ab 100644
--- a/src/org/apache/fop/render/ps/PSStream.java
+++ b/src/org/apache/fop/render/ps/PSStream.java
@@ -1,29 +1,50 @@
 /*
  * $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.render.ps;
 
-import java.io.*;
+import java.io.OutputStream;
+import java.io.FilterOutputStream;
+import java.io.IOException;
 
+/**
+ * PSStream is used to to output PostScript code from the PostScript renderer.
+ */
 public class PSStream extends FilterOutputStream {
 
+    /** @see java.io.FilterOutputStream **/
     public PSStream(OutputStream out) {
         super(out);
     }
-    
+
+
+    /**
+     * Writes a PostScript command to the stream.
+     *
+     * @param cmd              The PostScript code to be written.
+     * @exception IOException  In case of an I/O problem
+     */
     public void write(String cmd) throws IOException {
-        if (cmd.length() > 255)
+        if (cmd.length() > 255) {
             throw new RuntimeException("PostScript command exceeded limit of 255 characters");
+        }
         write(cmd.getBytes("US-ASCII"));
         write('\n');
     }
-    
+
+
+    /**
+     * Writes encoded data to the PostScript stream.
+     *
+     * @param cmd              The encoded PostScript code to be written.
+     * @exception IOException  In case of an I/O problem
+     */
     public void writeByteArr(byte[] cmd) throws IOException {
         write(cmd);
         write('\n');
     }
+
 }
diff --git a/src/org/apache/fop/render/ps/RunLengthEncodeOutputStream.java b/src/org/apache/fop/render/ps/RunLengthEncodeOutputStream.java
index a006bc5b6..64778a3f2 100644
--- a/src/org/apache/fop/render/ps/RunLengthEncodeOutputStream.java
+++ b/src/org/apache/fop/render/ps/RunLengthEncodeOutputStream.java
@@ -16,41 +16,30 @@ import java.io.IOException;
  * @author   <a href="mailto:smwolke@geistig.com">Stephen Wolke</a>
  * @version  $Id$
  */
-
 public class RunLengthEncodeOutputStream extends FilterOutputStream
             implements Finalizable {
 
-    private final static int MAX_SEQUENCE_COUNT = 127;
-    private final static int END_OF_DATA = 128;
-    private final static int BYTE_MAX = 256;
+    private static final int MAX_SEQUENCE_COUNT    = 127;
+    private static final int END_OF_DATA           = 128;
+    private static final int BYTE_MAX              = 256;
 
-    private final static int NOT_IDENTIFY_SEQUENCE = 0;
-    private final static int START_SEQUENCE = 1;
-    private final static int IN_SEQUENCE = 2;
-    private final static int NOT_IN_SEQUENCE = 3;
+    private static final int NOT_IDENTIFY_SEQUENCE = 0;
+    private static final int START_SEQUENCE        = 1;
+    private static final int IN_SEQUENCE           = 2;
+    private static final int NOT_IN_SEQUENCE       = 3;
 
     private int runCount = 0;
     private int isSequence = NOT_IDENTIFY_SEQUENCE;
     private byte[] runBuffer = new byte[MAX_SEQUENCE_COUNT + 1];
 
 
-    /**
-     * Constructor for the RunLengthEncode Filter.
-     *
-     * @param out  The OutputStream to write to
-     */
+    /** @see java.io.FilterOutputStream **/
     public RunLengthEncodeOutputStream(OutputStream out) {
         super(out);
     }
 
 
-    /**
-     * @see        java.io.OutputStream#write(int)
-     * @param      b   the <code>byte</code>.
-     * @exception  IOException  if an I/O error occurs. In particular,
-     *             an <code>IOException</code> may be thrown if the
-     *             output stream has been closed.
-     */
+    /** @see java.io.FilterOutputStream **/
     public void write(byte b)
         throws java.io.IOException {
         runBuffer[runCount] = b;
@@ -131,11 +120,7 @@ public class RunLengthEncodeOutputStream extends FilterOutputStream
     }
 
 
-    /**
-     * @see        java.io.OutputStream#write(byte[])
-     * @param      b   the data.
-     * @exception  IOException  if an I/O error occurs.
-     */
+    /** @see java.io.FilterOutputStream **/
     public void write(byte[] b)
         throws IOException {
 
@@ -145,15 +130,7 @@ public class RunLengthEncodeOutputStream extends FilterOutputStream
     }
 
 
-    /**
-     * @see        java.io.OutputStream#write(byte[], int, int)
-     * @param      b     the data.
-     * @param      off   the start offset in the data.
-     * @param      len   the number of bytes to write.
-     * @exception  IOException  if an I/O error occurs. In particular,
-     *             an <code>IOException</code> is thrown if the output
-     *             stream is closed.
-     */
+    /** @see java.io.FilterOutputStream **/
     public void write(byte[] b, int off, int len)
         throws IOException {
 
@@ -163,12 +140,7 @@ public class RunLengthEncodeOutputStream extends FilterOutputStream
     }
 
 
-    /**
-     * Flushes the the stream and writes out the trailer, but, unlike close(),
-     * without closing the stream.
-     *
-     * @exception  IOException  if an I/O error occurs.
-     */
+    /** @see org.apache.fop.render.ps.Finalizable **/
     public void finalizeStream()
         throws IOException {
         switch (isSequence) {
@@ -190,11 +162,7 @@ public class RunLengthEncodeOutputStream extends FilterOutputStream
     }
 
 
-    /**
-     * Closes the stream.
-     *
-     * @exception  IOException  if an I/O error occurs.
-     */
+    /** @see java.io.FilterOutputStream **/
     public void close()
         throws IOException {
         finalizeStream();